Writing postmortems

technical-writing

Overview

When to invoke, and not

Skeleton

# [System]: [the failure, as its symptom, one line]

| | |
|---|---|
| **Incident date** | YYYY-MM-DD |
| **Duration** | detection to resolution |
| **Severity** | [per the org taxonomy, defined where used] |
| **Status** | Draft / Reviewed |

## Summary
[User-visible impact with numbers, the root cause in one sentence, current state.
The reader who stops here still knows what happened.]

## Impact
[Who and what, quantified: requests failed, records affected, money or time lost.
Estimates labeled as estimates; "no evidence of data loss" only if actually checked,
and say what was checked.]

## Timeline
[Timestamped entries, facts only, each traceable to evidence: an alert, a log line,
a commit, a message. Interpretation lives in the sections below, never here.]

## Root cause and contributing factors
[The mechanism, grounded in code and commits. Contributing factors as a list:
real incidents rarely have one cause, and "every component was correct and the
defect lived between them" is a valid root cause. Name which layer of checking
missed it and which caught it.]

## What we got wrong during response
[The wrong first fix, the misleading signal followed, the theory that cost an hour.
Recording the plausible-but-wrong path is what saves the next responder from it.]

## Action items
[Each with an owner and an acceptance check, filed as tracker issues and linked.
"Investigate X" without an owner is banned here as everywhere.]

Rules

• Blameless means structural. Name the role, the gate, the dependency, the missing guard; never the person. This is not politeness: a postmortem blaming a person stops at "be more careful", and one blaming a structure produces an action item. The rule governs the narrative (timeline, causes, response); action-item ownership is assignment, not blame: a role in this document, an individual in the linked tracker issue.
• The timeline is evidence, not narrative. Every entry traces to something checkable, timestamps from the systems rather than memory. Where memory is the only source, say so.
• Wrong fixes are content. The fix that made sense and did not work belongs in the document with the reasoning that made it plausible; embarrassment is not a retention policy.
• Severity comes from the org taxonomy and is defined where used, not assumed. No taxonomy available: leave the field explicitly unassigned rather than inventing one.
• Action items follow

  writing-issues

  : outcome, owner, acceptance check, filed and linked, never left as prose intentions in the postmortem. When filing is not possible from where you sit, mark each item

  [to file: <who files it>]

  ; the postmortem stays Draft until the links exist.
• Immutable once reviewed. New findings are dated addenda; a rewritten postmortem is a falsified record. The review itself goes in a sign-off line (see

  references/truth.md

  in the core skill).
• Near misses use the same skeleton with Impact describing what would have happened, labeled as the counterfactual it is.

recording-decisions

writing-runbooks