Postmortem format: what makes a debugging writeup actually useful

I have written a lot of postmortems, and read even more, mostly other teams’ incidents forwarded around because someone thought “you should see this.” Most get read once, argued about in a meeting, and never opened again. A few get reread months later by someone hitting a similar problem, and those actually teach something. The difference is rarely how bad the incident was. It is almost entirely about how the document is written.

Timeline first, narrative second

The instinct when writing a postmortem is to explain what happened the way you would tell a coworker over coffee: “so we deployed the new caching layer, and then things seemed fine for a while, but then…” That is a story, easy to follow but hard to verify and hard to skim.

What holds up better is a timeline with timestamps, followed by a short narrative that connects the dots:

14:02 UTC  Deploy of cache-service v2.4.1 completes
14:09 UTC  Error rate on /checkout climbs from 0.1% to 4%
14:11 UTC  First PagerDuty alert fires (checkout error budget burn)
14:14 UTC  On-call acknowledges, starts checking recent deploys
14:22 UTC  cache-service v2.4.1 identified as likely cause, rollback started
14:26 UTC  Rollback complete, error rate returns to baseline
14:40 UTC  Incident declared resolved

Anyone can scan that in ten seconds and know the shape of the incident: twenty minutes of impact, twelve minutes from alert to root cause, four minutes to mitigate. That is useful before you have read a single sentence of explanation. The narrative below it answers “why,” not “when,” and stays honest because the timestamps anchor it to what was actually observed instead of what feels like a clean story in hindsight.

Root cause has to be specific enough to falsify

“Human error” is not a root cause. Neither is “the deploy went wrong” or “a config issue.” These are true in the way that “the code had a bug” is true of every incident ever. If your root cause section could be copy-pasted into a different postmortem without anyone noticing, it is not specific enough.

A root cause that actually helps someone reading it in six months looks like: “The cache TTL for the pricing table was set to 0 in the new config schema instead of inheriting the 300-second default, because the migration script only copied keys that existed in the old schema, and TTL was previously implicit.” That sentence lets a reader check their own service for the same class of bug, implicit defaults getting silently dropped during a schema migration, which is the entire point of writing this down.

A good test: could someone who was not in the incident channel read your root cause and go check whether the same thing could happen to their service? If not, keep digging.

Five whys gets you to an answer, not necessarily the right one

Five whys is a fine starting technique because it forces you past the first, laziest explanation. But it assumes a single causal chain, when most real incidents are a handful of independent things that each had to go wrong at the same time. Chase only one thread and you fix one thing while leaving the others in place for the next incident to find.

The fix is boring: after your five whys, ask “what else had to be true for this to cause an outage?” In the cache example above, the missing TTL was necessary but not sufficient. It also required that nobody had alerting on cache TTL values, that staging did not have enough traffic to reveal stale pricing data, and that there was no canary step between the config migration and full rollout. Each of those is its own fixable gap, and a postmortem that only reports the first one leaves the other three sitting there.

Detection, mitigation, and prevention are three different questions

These get conflated constantly, and they lead to different kinds of action items:

• Detection: how did we find out, and how long did it take? If the answer is “a customer tweeted about it,” that is itself a finding, independent of whatever caused the outage.
• Mitigation: what stopped the bleeding, and could it have been faster? Rollback in four minutes because someone happened to remember the deploy button under pressure is not repeatable; the action item is to make it a documented, one-command process.
• Prevention: what stops this exact class of bug from recurring? Not “review configs more carefully,” which nobody will actually do differently, but something concrete like a schema validation step that fails the migration if a required field has no explicit value.

Separating these stops the document from turning into a wall of vague resolutions. “We will be more careful” is not an action item. “Add a CI check that diffs config schema keys against the previous version and flags anything that lost its default silently” is.

Cut the blame, keep the specifics

There is a real tension here. You want the document to avoid making it about a person, because once postmortems become about assigning fault, people stop being honest in them and you lose the information you actually need. But “avoid blame” gets misapplied into “avoid specifics,” and that guts the document.

The distinction is: name the decision, not the person, and describe the conditions that made the decision reasonable at the time. “The engineer should have caught this” is blame. “The migration script’s test suite covered adding new keys but not a key silently losing its default value, so no existing test would have caught this” is specific and does not require anyone to feel bad reading it. It also points at a process gap instead of a person’s competence, which is the more useful place to point.

What people actually reopen these documents for

A postmortem gets reread for one of two reasons: someone is debugging something that smells similar and searching for a match, or someone is doing a periodic review of incident patterns and wants to see if the same root cause keeps showing up in different clothes. Both depend on the document being searchable and specific, not well-written. Optimize for the person skimming six months from now with a half-formed hunch, not the person in the retro meeting an hour after the incident. The retro audience already has context. The future reader has none, and that is who the document is actually for.