Postmortem Writing

Parent: Writing and Documentation · researched 2026-05-29T18:25:33.177Z· 14 sources · 10 concepts · skill postmortem-writing

A postmortem is a learning artifact disguised as an incident report. It must satisfy three audiences simultaneously: the engineers who need to understand what failed, the leadership who need to evalua

Overview

A postmortem is a learning artifact disguised as an incident report. It must satisfy three audiences simultaneously: the engineers who need to understand what failed, the leadership who need to evaluate organizational risk, and the people who lived through the incident. [source]

1. Blameless framing in prose — the system, not the human

Three substitutions do most of the work: [source]
Names → roles. "Alice deployed the bad change" → "The release engineer deployed change #4821." [source]
Judgments → actions. "Bob failed to notice the alert" → "The on-call engineer did not see the alert because it was routed to a paused channel." [source]
Causal verbs → enabling conditions. "X caused Y" → "X created conditions under which Y became possible." [source]
The single most damaging phrase: "should have." Replace it with "the system did not surface the information that would have enabled X." [source]

2. Timeline reconstruction in UTC

UTC timestamps, always. [source]
Source for each event: which dashboard, which log line, which Slack message. [source]
Actor + action + observable result, in that order. [source]
Decision points called out explicitly, with the information the decider had at the time. [source]

3. Contributing factors vs root cause

Real incidents have a root cause plus contributing factors. Structure the analysis as: [source]
Triggering event (the proximate change). [source]
Root cause (the latent defect the trigger exposed). [source]
Contributing factors, categorized: [source]
Technical (missing monitoring, single points of failure) [source]
Process (insufficient testing, communication gaps) [source]
Environmental (time pressure, on-call fatigue) [source]

4. Five Whys discipline

Apply iteratively: "Why did the API return 503s? Because the database connection pool was exhausted." Continue until you reach an organizational or design-level factor. [source]
Allow branching. A single chain of whys is rare. Multiple parallel chains converging on multiple contributing factors is common. [source]

5. Action items with owners, dates, severity, and traceability

A defensible action item has: [source]
Owner: a single named person (not a team). [source]
Due date: a real calendar date. [source]
Severity / priority: P0/P1/P2 calibrated to actual risk reduction. [source]
Traceability: which contributing factor it addresses. [source]
Definition of done: how the writer will know the action is complete. [source]

6. "What went well" without performative positivity

What worked: the alert fired correctly, the rollback procedure was executable. [source]
What we got lucky on: things that worked but only by accident. [source]
What we want to preserve: practices that should be formalized. [source]

7. Hindsight bias — naming it and writing around it

Linguistic markers of hindsight bias to delete in revision: [source]
"Clearly..." (it was not clear at the time). [source]
"Obviously..." (it was not obvious to anyone in the moment). [source]
"Should have noticed..." (replace with "the available signals did not surface X"). [source]

8. The hourglass structure for postmortems

The top (inverted pyramid summary, 4–6 paragraphs). The verdict first: what broke, when, who was affected, severity, root cause class. [source]
The turn (one sentence). "Here is how the incident unfolded, in chronological order." [source]
The bottom (chronological narrative). The timeline. [source]

Anti-Patterns

Single-root-cause syndrome: "the root cause was X" with no contributing factors. [source]
Wishlist action items: "we should also rewrite the deployment system." [source]
Hindsight prose: "obviously the team should have noticed..." [source]
The publish-and-forget: no review date, no owner for action items. [source]

References

Google SRE Book - Chapter 15: Postmortem Culture [source]
Etsy - Debriefing Facilitation Guide (Allspaw, Evans, Schauenberg) [source]
Atlassian - Postmortems: Enhance Incident Management Processes [source]

Children

Blameless framing in prose (system not human) (frontier)
Timeline reconstruction in UTC with source-of-truth (frontier)
Contributing factors vs root cause distinction (frontier)
Five Whys discipline (not literally five, never one) (frontier)
Action items with owners, dates, severity, traceability (frontier)
What went well without performative positivity (frontier)
Hindsight bias and the linguistic markers to delete (frontier)
Customer impact section (quantified, time-bounded, honest) (frontier)
Publication and review ritual (frontier)
Sensitive incidents (security, privacy, legal review) (frontier)

Frontier under this node: Action items with owners, dates, severity, traceability, Blameless framing in prose (system not human), Contributing factors vs root cause distinction, Customer impact section (quantified, time-bounded, honest), Five Whys discipline (not literally five, never one), Hindsight bias and the linguistic markers to delete, Publication and review ritual, Sensitive incidents (security, privacy, legal review), Timeline reconstruction in UTC with source-of-truth, What went well without performative positivity

← the whole tree · 3D view· how to read this page