# Appendix: Reusable Templates > From *The Confident Learner: Tech and Domain Fundamentals for the AI Era* by Dharanova Pioneer, a free online book. > Web page: https://elephantbamboo.com/appendix/templates · Licence: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/) *Seven small artifacts this book keeps telling you to write, shown as actual templates instead of general advice. Each one moves from a bad version to a better one to a strong one, so you can see exactly what improves at each step, not just that improvement is possible.* Do not treat "strong" as the only acceptable version. A "better" sent today is worth more than a "strong" you never send because you were still polishing it. These are here so you know what strong looks like when you have the extra five minutes, not to raise the bar for every message you will ever write. --- ## 1. A question to a senior *Referenced in Chapter 15, Section 4.* **Bad.** > hey my code isn't working, can someone help? This transfers the entire cost of the problem — understanding it, reproducing it, diagnosing it — onto whoever answers, and signals you have not yet paid that cost yourself. **Better.** > Hi, I'm getting a 403 error when I call the payments endpoint. Any idea why? An improvement — there is now a specific symptom — but it still leaves the reader to ask three follow-up questions before they can help: which endpoint, what did you send, what have you tried. **Strong.** > Hi — I'm getting a 403 Forbidden calling `POST /v1/payments` with my test API key. The same key works fine on `GET /v1/merchants`, so I don't think the key itself is invalid. I'm sending it as `Authorization: Bearer `, which matches the docs. I checked the API reference and don't see a separate permission needed for write endpoints, but I might be missing something. I've attached the exact request and the full response. Do you know if test keys need a different scope for POST requests, or does this look like something else? Notice the shape: what you were trying to do, what you observed, what you already ruled out, what you have already checked, and a specific question at the end. This is faster for the reader, and it is very often the case that writing it this precisely answers your own question before you send it. --- ## 2. A pull-request description *Referenced in Chapter 12 and Chapter 15.* **Bad.** > fix bug **Better.** > Fixed the double-charge bug in checkout. Added a check before processing the payment. **Strong.** > **What.** Adds an idempotency key check to the `/checkout` endpoint. > > **Why.** Users on flaky connections were occasionally being charged twice (see INC-482). The purchase request was sent over a method browsers will silently retry, and the server had no way to recognise a retry from a fresh request. > > **How tested.** Added a test that sends the same idempotency key twice and asserts only one charge is recorded. Manually tested by throttling my network in dev tools and retrying a purchase. > > **Rollout.** No schema change, no feature flag needed — this only adds a check, it does not remove any existing behaviour. Safe to deploy directly. > > **Rollback.** Revert this commit; the endpoint returns to its previous behaviour with no data migration needed either way. A reviewer who has never seen the ticket can understand this PR in under a minute, which is exactly the point of a good description: it is written for someone who has not been living inside the problem with you. --- ## 3. A one-page design note *Referenced in Chapter 15, Section 6.* **Bad.** A message in Slack: "going to add caching to the search endpoint, starting now." **Better.** A short doc: "We'll cache search results for 60 seconds to reduce database load." **Strong.** > **Problem.** The search endpoint is the single largest source of database load, and it is growing with traffic. Most searches are for the same handful of popular queries within any given hour. > > **Options considered.** > 1. Add a read replica — reduces load but doesn't reduce redundant work, and adds infrastructure cost. > 2. Cache search results in Redis, keyed by query, with a short TTL — cuts redundant work directly. > 3. Precompute results for known popular queries — most targeted, but only covers queries we predict in advance. > > **Chosen approach.** Option 2. It is the simplest to build, it directly addresses the redundant-work problem rather than just adding capacity, and it degrades safely — if the cache is unavailable, requests fall through to the database exactly as they do today. > > **Risks.** Stale results for up to 60 seconds after a document changes. Acceptable here because search results are not safety- or money-critical (unlike, say, a stock count) — this is exactly the eventual-consistency trade-off Chapter 10 describes, made deliberately and written down. > > **Rollback.** A single feature flag disables the cache and returns to direct database queries. No data migration in either direction. > > **Open questions.** Should the TTL differ for logged-in vs anonymous users? Leaving this for a follow-up rather than blocking on it now. The value of a one-pager is not the document itself. It is that writing "options considered" forces you to have actually considered more than one option, and writing "risks" and "rollback" forces you to have thought about them before you need them at 2 AM. --- ## 4. An incident hypothesis log *Referenced in Chapter 11.* **Bad.** No log at all — just a growing, unstructured Slack thread that is impossible to reconstruct afterward. **Better.** A single running note: "Think it might be the SMS provider. Checking now." **Strong.** A simple table, updated live during the incident: | Time | Hypothesis | Evidence for | Evidence against | Status | |---|---|---|---|---| | 14:02 | Booking service is down | Error rate spiked at 14:00 | Booking service's own health check is green | Ruled out | | 14:06 | Database is slow | Some queries in the trace show 800ms+ | Most queries are fast; only bookings touching SMS are slow | Investigating | | 14:11 | SMS provider is timing out | All slow traces converge on the SMS call; provider status page shows a degraded banner | — | Confirmed | | 14:14 | Fix: add a timeout + async retry on SMS call so it stops blocking the booking response | — | — | Deploying | This is what Lavanya's senior effectively did in twenty minutes in Chapter 11's opening story, made explicit. The log does two things a Slack thread does not: it makes "what have we already ruled out" visible to everyone joining the incident late, and it forces every hypothesis to name its evidence, which is the exact discipline that separates a guess from a diagnosis. --- ## 5. A five-thing map *Taught in full in Chapter 17. This is the fillable version.* **Domain:** _______________ | Element | Fill in | |---|---| | **Vocabulary** | The 10–15 terms you hear repeatedly that you could not yet define precisely to a colleague. | | **Actors & incentives** | Who is in the system, and — stated as a hypothesis about how each one is paid or measured, not a guess about their character — what each one is optimising for. | | **Money flow** | Draw it left to right: where money enters, who takes a cut, where it ends up, what regulatory floors or ceilings constrain it. | | **Regulatory perimeter** | Which body regulates this domain, and where their primary published guidance actually lives (a URL, not a memory). | | **Failure modes** | Ask one practitioner: "What are the ways this goes badly wrong, and what happens when it does?" Write down what they say, not what you'd guess. | **Worked example — a first pass at "school-fee payment portals," a domain not covered elsewhere in this book:** - *Vocabulary:* fee head, late-fee waiver, RTE quota, TC (transfer certificate) hold, reconciliation cycle. - *Actors:* the parent (wants a fast, low-friction payment and a receipt for tax purposes), the school's accounts office (wants every payment matched to the right student and fee head with no manual reconciliation), the payment gateway (wants transaction volume and low dispute rates), the state education department (wants RTE-quota fee waivers correctly applied and auditable). - *Money flow:* parent pays gateway → gateway settles to school's account, typically T+1 → school's accounts office reconciles against its own student ledger → discrepancies get chased manually, often for weeks, at the start of every term. - *Regulatory perimeter:* varies by state and by whether the school is government-aided; RTE Act fee-waiver rules are central government but state-implemented — check the specific state education department's own circular, not a generic summary. - *Failure modes (hypothesis, not yet checked with a practitioner):* a payment succeeding at the gateway but failing to match to the right student due to a typo'd admission number; an RTE waiver applied incorrectly, generating a fee demand a quota student should never have received. Notice that the "failure modes" row is explicitly marked as an unverified hypothesis here — exactly the discipline Chapter 17 and Chapter 18 both ask for. A real map gets that row from a practitioner, not from a first guess. --- ## 6. A domain-expert outreach message *Referenced in Chapter 18, Section 4, and Chapter 22.* **Bad.** > Hi! I'd love to pick your brain about the insurance industry sometime, would you be free for a chat? Vague enough that the recipient cannot tell what you actually want, or how long it will take. **Better.** > Hi, I'm a student interested in insurance tech. Could we talk sometime about your work? **Strong.** > Hi [Name] — I'm a final-year student at [college], and I've been trying to understand how TPA claims processing actually works in Indian health insurance (I've read through IRDAI's public guidance and built a rough map of the actors involved, but there are gaps only someone who's lived it could fill). I saw you've worked in claims operations for a few years and thought you might be a good person to ask. Would you have twenty to thirty minutes for a call sometime in the next couple of weeks? Happy to work around your schedule, and happy to send specific questions in advance if that's easier for you. The strong version works because it proves you have already done homework (so the conversation adds new value instead of repeating a Google search), states a specific, bounded ask (thirty minutes, not "sometime"), and gives the person an easy way to say yes (flexible timing, questions in advance if they prefer to prepare). --- ## 7. A checklist for evaluating an internship *Referenced in Chapter 22.* Before accepting, or while deciding between options, answer these honestly: - **Mentor.** Is there a specific person who will actually spend time with you, or will you be handed a laptop and left alone? Ask directly: "Who would I be working most closely with day to day?" - **Scope.** Is the work clearly bounded, or vague enough that it could expand into unpaid full-time hours? Ask: "What would a typical week look like?" - **Pay.** Is it paid? If unpaid, is "exposure" or "experience" honestly worth what you are giving up, or is that framing doing a lot of unearned work? - **Hours.** Are the expected hours compatible with your classes or exams, stated plainly, not implied? - **Safety.** Would you be comfortable telling a parent, a professor, or a placement officer exactly what the role involves and who is offering it? - **Legitimacy.** Is this a real team at a real organisation you can describe in one sentence to a future interviewer without it sounding vague or improvised? - **Domain fit.** Does it put you in contact with real production data or decisions in a domain you have already done five-thing-map homework for — the highest-leverage signal, but only after the six checks above pass. A domain match that fails several of the first six checks is not a good internship. It is a good domain wrapped around a bad situation.