Postmortem Writing
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/postmortem-writing.md
↓ Facts as markdownall context files
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
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#overview]
1. Blameless framing in prose — the system, not the human
- Three substitutions do most of the work: [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#1-blameless-framing-in-prose-the-system-not-the-human]
- Names → roles. "Alice deployed the bad change" → "The release engineer deployed change #4821." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#1-blameless-framing-in-prose-the-system-not-the-human]
- 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." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#1-blameless-framing-in-prose-the-system-not-the-human]
- Causal verbs → enabling conditions. "X caused Y" → "X created conditions under which Y became possible." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#1-blameless-framing-in-prose-the-system-not-the-human]
- The single most damaging phrase: "should have." Replace it with "the system did not surface the information that would have enabled X." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#1-blameless-framing-in-prose-the-system-not-the-human]
2. Timeline reconstruction in UTC
- UTC timestamps, always. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#2-timeline-reconstruction-in-utc]
- Source for each event: which dashboard, which log line, which Slack message. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#2-timeline-reconstruction-in-utc]
- Actor + action + observable result, in that order. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#2-timeline-reconstruction-in-utc]
- Decision points called out explicitly, with the information the decider had at the time. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#2-timeline-reconstruction-in-utc]
3. Contributing factors vs root cause
- Real incidents have a root cause plus contributing factors. Structure the analysis as: [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
- Triggering event (the proximate change). [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
- Root cause (the latent defect the trigger exposed). [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
- Contributing factors, categorized: [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
- Technical (missing monitoring, single points of failure) [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
- Process (insufficient testing, communication gaps) [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
- Environmental (time pressure, on-call fatigue) [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#3-contributing-factors-vs-root-cause]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#4-five-whys-discipline]
- Allow branching. A single chain of whys is rare. Multiple parallel chains converging on multiple contributing factors is common. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#4-five-whys-discipline]
5. Action items with owners, dates, severity, and traceability
- A defensible action item has: [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#5-action-items-with-owners-dates-severity-and-traceability]
- Owner: a single named person (not a team). [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#5-action-items-with-owners-dates-severity-and-traceability]
- Due date: a real calendar date. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#5-action-items-with-owners-dates-severity-and-traceability]
- Severity / priority: P0/P1/P2 calibrated to actual risk reduction. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#5-action-items-with-owners-dates-severity-and-traceability]
- Traceability: which contributing factor it addresses. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#5-action-items-with-owners-dates-severity-and-traceability]
- Definition of done: how the writer will know the action is complete. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#5-action-items-with-owners-dates-severity-and-traceability]
6. "What went well" without performative positivity
- What worked: the alert fired correctly, the rollback procedure was executable. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#6-what-went-well-without-performative-positivity]
- What we got lucky on: things that worked but only by accident. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#6-what-went-well-without-performative-positivity]
- What we want to preserve: practices that should be formalized. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#6-what-went-well-without-performative-positivity]
7. Hindsight bias — naming it and writing around it
- Linguistic markers of hindsight bias to delete in revision: [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#7-hindsight-bias-naming-it-and-writing-around-it]
- "Clearly..." (it was not clear at the time). [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#7-hindsight-bias-naming-it-and-writing-around-it]
- "Obviously..." (it was not obvious to anyone in the moment). [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#7-hindsight-bias-naming-it-and-writing-around-it]
- "Should have noticed..." (replace with "the available signals did not surface X"). [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#7-hindsight-bias-naming-it-and-writing-around-it]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#8-the-hourglass-structure-for-postmortems]
- The turn (one sentence). "Here is how the incident unfolded, in chronological order." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#8-the-hourglass-structure-for-postmortems]
- The bottom (chronological narrative). The timeline. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#8-the-hourglass-structure-for-postmortems]
Anti-Patterns
- Single-root-cause syndrome: "the root cause was X" with no contributing factors. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#anti-patterns]
- Wishlist action items: "we should also rewrite the deployment system." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#anti-patterns]
- Hindsight prose: "obviously the team should have noticed..." [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#anti-patterns]
- The publish-and-forget: no review date, no owner for action items. [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#anti-patterns]
References
- Google SRE Book - Chapter 15: Postmortem Culture [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#references]
- Etsy - Debriefing Facilitation Guide (Allspaw, Evans, Schauenberg) [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#references]
- Atlassian - Postmortems: Enhance Incident Management Processes [archived source: https://llms-explorer.com/sources/mdb-context-hub/postmortem-writing/#references]
Where this helps
- Writing up a production outage in a way that engineers, leadership, and the people who lived through it can all extract what they need without three separate documents. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Facilitating a postmortem review meeting where the draft keeps drifting into blame ("Bob failed to notice") and needs reframing before it's shared widely. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding how deep to push a Five Whys chain when an incident review keeps stopping at a superficial technical cause instead of reaching the organizational factor underneath. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Building an action-item tracker from a completed postmortem where vague "we should also rewrite X" items need to be converted into owned, dated, traceable commitments. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Run the three substitutions (names→roles, judgments→actions, causal verbs→enabling conditions) as a dedicated revision pass after the first draft, rather than trying to write blamelessly on the first attempt. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Reconstruct the timeline in UTC with a cited source for every event before writing the narrative prose, so the chronological section is built from evidence rather than memory. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Structure the analysis explicitly as triggering event, root cause, and categorized contributing factors (technical/process/environmental), resisting the pull toward naming a single root cause. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Delete hindsight-bias markers ("clearly," "obviously," "should have noticed") in a dedicated revision pass, replacing each with a sentence naming what information was actually available at the time. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Common mistakes
- Single-root-cause syndrome — naming one root cause with no contributing factors, when most real incidents have a root cause plus several technical, process, and environmental contributors. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing wishlist action items ("we should also rewrite the deployment system") instead of scoped, owned, dated commitments traceable to a specific contributing factor. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Leaving hindsight-bias prose in the final draft ("obviously the team should have noticed...") which reads as blame even when the intent was analytical. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Publishing the postmortem and never assigning a review date or an owner to the action items, so the document becomes a historical record instead of a driver of change. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Blameless framing is a writing discipline, not a guarantee — a report that swaps names for roles can still read as blame if the underlying analysis singles out one team's actions as the story. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The Five Whys technique can converge on a plausible-sounding but wrong organizational factor if the chain isn't allowed to branch; real incidents usually have multiple parallel causal chains, not one. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A defensible action item requires a single named owner, which can create friction in organizations that prefer team-level accountability — the postmortem format assumes individual ownership is achievable. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The hourglass structure front-loads the verdict before the evidence, which serves skimmers well but means a reader who stops at the summary may miss caveats and nuance that only appear in the full timeline. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
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