I've read a lot of postmortems. Most of them are written for an audience that doesn't exist.
They're five pages long. They have an "Executive Summary" for executives who will never open the doc. They have a root-cause section that stops at "human error" (never the root, always an excuse to stop digging). And they end with action items like "improve monitoring" — assigned to nobody, due never, closed by nobody.
Then the same incident happens eight months later, and someone says "wait, didn't we write this up last time?" and nobody can find the doc.
A postmortem has exactly one job: make the next incident shorter or prevent it entirely. Everything in the document either serves that job or is theater. Here's the format we landed on after writing plenty of theatrical ones — it fits on one page, takes under an hour, and people actually read it. Template is at the bottom; steal it.
The three failure modes that kill postmortems
1. They're written to assign blame while claiming not to. Everyone says "blameless," then writes a timeline where one person's name appears eleven times. Here's the practical test of blamelessness: replace every name in the doc with a role ("the on-call engineer," "the reviewer"). If the story stops making sense, your postmortem was about a person, not a system. Systems can be fixed; shaming a person just teaches everyone to hide the next mistake — and hidden mistakes are how small incidents become big ones.
2. They're written too late. Two weeks after the incident, memories have quietly rewritten themselves into a cleaner story than what happened. The messy truth — the ten minutes spent debugging the wrong service, the alert everyone swiped away — is exactly the valuable part, and it evaporates first. Draft the timeline within 48 hours, even if the meeting happens later.
3. Nobody can reconstruct what actually happened. This one's structural. The incident lived across your alerting tool, an error tracker, three chat threads, a DM where the actual fix was discussed, and a deploy log. Assembling a truthful timeline means archaeology across five tools, so people skip it and write vibes instead. (This scattered-evidence problem is half of why I'm building triage that catches on-call alerts in one queue — but you don't need tooling to start: just make "paste timestamps into the doc as things happen" an on-call habit. Future-you, doing archaeology at 5 PM on a Friday, will be grateful.)
What actually belongs in the doc
A timeline with timestamps, including the embarrassing parts
Not a narrative — a table. When did the issue start (not when was it detected — the gap between those two numbers is one of your most important findings). When did the first human notice. What did they try. What didn't work.
The wrong turns are the whole point. "We spent 25 minutes restarting the API before realizing it was the database" is not embarrassing filler — it's the single most reusable finding in the doc, because the next person will make the same wrong turn unless you write it down.
"Why did our safeguards not catch this?" — the only root-cause question that matters
Skip the Five Whys ritual if it doesn't suit you, but do not skip this question. Every incident that reaches production walked past every defense you have: tests, review, staging, alerts, rate limits. The bug is rarely the interesting part. The interesting part is the hole in the net.
- Why didn't tests catch it? (No coverage there? Coverage exists but the case is untestable?)
- Why didn't review catch it? (Diff too big? Reviewer had no context? Rubber-stamp culture?)
- Why didn't alerts catch it before users did? (This one hurts the most and teaches the most.)
Note the shape of these questions: they're all about the system. That's what blameless actually means — not "no accountability," but "the system failed, and the system is what we can change."
Three action items, maximum
This is the most opinionated rule in our format, and the one I'll defend hardest.
A postmortem with twelve action items produces zero completed action items. Twelve items means nobody prioritized, so the backlog will — which means none of them ship. Force the ranking: what are the three changes with the best ratio of "prevents recurrence" to "effort"? Each one gets a single named owner (a person, not a team — a team owner is no owner) and a date. Everything else you thought of goes in a "considered but not doing" list, with the reason. That list is quietly the most honest section of the doc, and it saves the next incident's responders from re-litigating ideas you already rejected.
And track them. An action item that isn't checked four weeks later is a decision to accept the risk — fine, but make it a decision, not a drift.
A "how will we detect this next time?" line
One sentence. If the answer is "same way — a customer will tell us," say so explicitly. Writing that sentence down is uncomfortable in exactly the way that gets a monitoring gap actually fixed.
The template
Copy this into your wiki. Ruthlessly delete any section you're tempted to add back — length is the enemy.
# [YYYY-MM-DD] Short, searchable title (name the system + symptom)
**Impact:** Who/what was affected, for how long, how badly.
One sentence. Numbers if you have them.
**Detection gap:** Issue started HH:MM · detected HH:MM · by [alert / customer / luck]
## Timeline (UTC)
| Time | What happened |
|-------|---------------|
| 09:12 | Deploy #482 ships |
| 09:14 | Error rate on auth-svc rises (no alert fires) |
| 09:31 | First customer report |
| 09:40 | On-call restarts API (wrong tree — 25 min lost) |
| 10:05 | DB connection pool identified as cause |
| 10:11 | Mitigated (rollback) |
## Why our safeguards missed it
- **Tests:** …
- **Review:** …
- **Alerts/monitoring:** …
## Root cause
2–4 sentences. If it ends at "human error," keep digging —
what made the error easy to make and hard to catch?
## Action items (max 3)
| # | Change | Owner (person) | Due | Done? |
|---|--------|----------------|-----|-------|
| 1 | | | | |
## Considered but not doing
- [Idea] — [reason we're accepting this risk]
## Next time, we'll detect this via
One sentence. Be honest if the answer is "we won't."
Anti-patterns to delete on sight
- "Human error" as root cause. It's where the analysis stops, never where the truth is.
- "Improve monitoring" as an action item. Which monitor? On what threshold? Owned by whom? Vague items are unfalsifiable, and unfalsifiable items are never done.
- The Word-doc graveyard. If postmortems aren't searchable from where engineers already work, they might as well not exist. The doc's title should contain the system name and the symptom, because that's what the next responder will frantically search for at 2 AM. ("We wrote this up last time" is only useful if last time is findable — the same reason duplicate tickets are a search problem before they're an AI problem.)
- Postmortems only for big incidents. The 20-minute near-miss teaches the same lesson as the 4-hour outage, at 5% of the cost. Write the small ones; they're cheaper tuition.
The uncomfortable summary
If your postmortems are long, late, blameful, and unfindable, people will treat them as punishment paperwork — and you'll get exactly the quality of analysis that punishment paperwork deserves. Make them one page, fast, systemic, and searchable, and they become the cheapest reliability investment you can make.
What's the best (or most cursed) postmortem practice you've seen at your company? Genuinely collecting these — the "considered but not doing" section above was stolen from a comment on a previous post.
Top comments (0)