The written record: tickets, PRs, commits, postmortems

Chat evaporates; the written record is what your team actually keeps. Bug reports, tickets, pull request descriptions, commit messages, release notes, runbooks, and postmortems are read months later by people with no context, often including a future version of you at 3 a.m. Each genre has a fixed anatomy, and filling the anatomy is faster than improvising, because the anatomy is exactly the list of questions readers will otherwise have to ask you.

The register rule for all of them: write for a stranger. No "the issue we discussed", no "the usual fix", no abbreviations that are local slang (Chapter 12's doc rule). The reader has your text and nothing else.

Bug reports

The anatomy, in order:

Title:      Checkout returns 500 when the cart contains only a gift card

Environment: prod, eu-west, Chrome and curl both; started ~2026-07-19
Steps:
  1. Create a cart with a single gift-card item (no physical goods)
  2. POST /checkout
Expected:   200 with order confirmation
Actual:     500; response body and trace ID below (verbatim)
Impact:     ~40 checkouts/day hit this path (query attached); workaround
            exists (add any physical item), so severity 3
Evidence:   trace 4f2a..., log excerpt, HAR file attached
Not it:     payment provider status page green; same fail with card
            payments disabled, so not the gateway

The parts that separate a report engineers thank you for from one they bounce back:

  • The title states symptom plus trigger, because titles are what triage sees. "URGENT: site broken!!" contains zero of either.
  • Steps are a numbered recipe starting from nothing. The gold standard is the minimal reproduction: the smallest input that still fails. Every step you strip is an hour the assignee does not spend.
  • Expected versus actual is the load-bearing pair; a surprising number of "bugs" dissolve when the reporter writes down what they expected.
  • Evidence is verbatim (Chapter 14): paste the exact error, never a paraphrase. "Some kind of auth error" is a séance; "403: token audience mismatch" is a diagnosis.
  • "Not it" (what you already ruled out) is the mark of a report by an engineer: it saves the assignee from re-walking your dead ends.

Don't be confused: severity and priority are different dimensions and most trackers have both. Severity is impact ("how bad is it when it happens"); priority is ordering ("how soon do we work on it"). A crash affecting one internal demo tool is high severity, low priority; a typo in the signup flow's pricing is low severity, very high priority. Filling one field from the other is the classic triage error, and "why is this P3, it crashes!" arguments are usually the two dimensions talking past each other.

Tickets and stories

For planned work, the reader's questions are scope questions, so the anatomy is: context (one paragraph), the change requested, acceptance criteria (the checkable list that defines done), and explicit non-goals. Acceptance criteria in the checkable form: "retries capped at 3; the cap is a config value; a metric counts exhausted retries." Vague tickets ("improve retry behavior") do not shrink work; they relocate the scoping argument to the code review, the most expensive place to have it.

Pull request descriptions

The reviewer's questions, in the order they have them:

What:      Cap checkout retries at 3 and surface a metric for exhaustion.
Why:       Uncapped retries amplified Tuesday's outage (INC-214); this is
           action item 2 from the postmortem.
How:       Config-driven cap in RetryPolicy; new counter checkout_retry_
           exhausted; no behavior change when the flag is unset.
Testing:   Unit tests for 0/1/n; ran the INC-214 replay locally, storm
           does not amplify. Screenshot of the new dashboard panel below.
Rollout:   Behind flag retry_cap, default off; enable per-region.
Rollback:  Flag off; no schema changes.
Links:     Fixes #4821. Postmortem: go/inc-214.

"What" and "why" are for every reader forever; "testing" and "rollback" are for the reviewer and the on-call. A PR description that says "see title" outsources all four to archaeology. Two habits worth stealing: state what you did not do ("does not touch the payment retries; that is #4830"), and when the diff looks bigger than the change, say why ("mostly mechanical rename; the real change is in retry_policy.py").

Commit messages

The convention, stable across most of the industry: a subject line in the imperative mood ("Add retry cap", not "Added" or "Adds"), around 50 characters, no trailing period; then a blank line; then a body that explains why, wrapped at ~72 characters. The imperative reads oddly until you notice it completes the sentence "if applied, this commit will...". The body is where you talk to the future debugger:

Cap checkout retries at 3

Uncapped retries turned a 2-minute payment blip into a 40-minute
brownout during INC-214: every failed checkout re-entered the queue
and competed with live traffic. A cap of 3 keeps the recovery
property (transient blips still heal) without the amplification.

The cap is config-driven because BFCM traffic may want 1.

Many teams add a type prefix (Conventional Commits: fix:, feat:, chore:) so changelogs can be generated; adopt whatever the repo already does. The anti-patterns are universal: "wip", "fix", "final fix", "actually final" tell the future nothing, and squashing them before merge is basic hygiene.

Release notes and changelogs

Two genres wearing one name. The changelog is for engineers: exhaustive, terse, per-change ("Cap checkout retries at 3 (#4821)"). Release notes are for users, written in outcomes and the second person: "Checkout now recovers faster during payment provider hiccups." The translation discipline is Chapter 20's whole subject; the one-line version is that users do not have retries, they have slow checkouts. Never let the internal name of a thing leak into user-facing notes ("fixed a bug in HydraQueue v2").

Runbooks

A runbook is instructions for a stressed person at 3 a.m., which sets the style rules: imperative sentences, exact commands (copy-pasteable, with placeholders marked), expected output after each step so the operator knows they are still on the path, and explicit decision points ("if the queue depth is falling, stop here; if not, continue"). The words should, probably, and usually are bugs in a runbook. So is any step that has never been executed; untested runbooks are fiction in a confident font, and the fix is a game day (a scheduled practice run).

Postmortems

The capstone genre, and the one with the strictest culture rules (Chapter 10). The standard skeleton:

  1. Summary: three sentences a director can read alone.
  2. Impact: who, what, how long, how many, in numbers.
  3. Timeline: timestamped facts only, no analysis mixed in ("14:02 alert fired; 14:09 acknowledged; 14:31 rollback started").
  4. Contributing factors: plural on purpose, systems not people (Chapter 7's blameless grammar). The trigger gets a sentence; the conditions get the pages.
  5. What went well / what went poorly: including in the response itself ("paging worked; the runbook was stale").
  6. Action items: each with an owner and a date, filed as real tickets. A postmortem whose action items are not tracked was a writing exercise, not an engineering artifact.

Write the timeline the day of the incident while the logs and memories agree, and write the analysis a day later when the adrenaline does not.

👉 The written record covers work; the next chapters cover people. First the conversation that shapes your career more than any design review: the 1:1 with your manager, and the language of feedback, promotion, and pay. On to Chapter 18.