Writing postmortems
REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).
Overview
A postmortem is written for the engineer who hits something similar in a year, not for the people in the room. Core principle: facts from evidence, causes from mechanisms, lessons from both, and no names. The document is historical by classification: once reviewed, it is immutable, and corrections are dated addenda.
When to invoke, and not
Invoke after an incident is resolved, or at a stable milestone of a long one. A defect that reached users and a near miss, where a guard caught what review missed, earn the same write-up. Do NOT invoke during the live incident: the runbook governs that. Do not invoke for assigning accountability, since a postmortem that needs a person's name to make sense is describing a process hole. And not for a status update to stakeholders, which is a report.
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.]
## Wrong turns during the 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.]
## Sign-off
[- YYYY-MM-DD <reviewer>: approved <scope>, one line per review event.]
Rules
- Blameless means structural. Name the role, the gate, the dependency, the missing guard; never the person. 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. When no taxonomy exists, 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.
The decision that often follows a postmortem (a new invariant, a policy change) is recorded via recording-decisions and linked, not embedded. Runbook updates that the incident exposed go through writing-runbooks in the same change as the fix, because documentation is part of done rather than a follow-up ticket.
1---2name: writing-postmortems3description: Use when writing a postmortem, incident report, or root-cause analysis after an outage, a defect that reached users, a data issue, or a near miss - or when turning an incident channel, alert log, or war-room thread into a durable document. Encodes the blameless framing, the evidence-only timeline, contributing factors, and owned action items. Use whenever something broke and the write-up must outlive the incident.4---5
6# Writing postmortems
7
8**REQUIRED BACKGROUND:** the `technical-writing` skill (hard rules, truth rules, style).
9
10## Overview
11
12A postmortem is written for the engineer who hits something similar in a year, not for the people in the room. Core principle: **facts from evidence, causes from mechanisms, lessons from both, and no names.** The document is historical by classification: once reviewed, it is immutable, and corrections are dated addenda.
13
14## When to invoke, and not
15
16Invoke after an incident is resolved, or at a stable milestone of a long one. A defect that reached users and a near miss, where a guard caught what review missed, earn the same write-up. Do NOT invoke during the live incident: the runbook governs that. Do not invoke for assigning accountability, since a postmortem that needs a person's name to make sense is describing a process hole. And not for a status update to stakeholders, which is a report.
17
18## Skeleton
19
20```markdown
21# [System]: [the failure, as its symptom, one line]
22
23| | |
24|---|---|
25| **Incident date** | YYYY-MM-DD |
26| **Duration** | detection to resolution |
27| **Severity** | [per the org taxonomy, defined where used] |
28| **Status** | Draft / Reviewed |
29
30## Summary
31[User-visible impact with numbers, the root cause in one sentence, current state.
32The reader who stops here still knows what happened.]
33
34## Impact
35[Who and what, quantified: requests failed, records affected, money or time lost.
36Estimates labeled as estimates; "no evidence of data loss" only if actually checked,
37and say what was checked.]
38
39## Timeline
40[Timestamped entries, facts only, each traceable to evidence: an alert, a log line,
41a commit, a message. Interpretation lives in the sections below, never here.]
42
43## Root cause and contributing factors
44[The mechanism, grounded in code and commits. Contributing factors as a list:
45real incidents rarely have one cause, and "every component was correct and the
46defect lived between them" is a valid root cause. Name which layer of checking
47missed it and which caught it.]
48
49## Wrong turns during the response
50[The wrong first fix, the misleading signal followed, the theory that cost an hour.
51Recording the plausible-but-wrong path is what saves the next responder from it.]
52
53## Action items
54[Each with an owner and an acceptance check, filed as tracker issues and linked.
55"Investigate X" without an owner is banned here as everywhere.]
56
57## Sign-off
58[- YYYY-MM-DD <reviewer>: approved <scope>, one line per review event.]
59```
60
61## Rules
62
63- **Blameless means structural.** Name the role, the gate, the dependency, the missing guard; never the person. 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.
64- **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.
65- **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.
66- **Severity comes from the org taxonomy** and is defined where used, not assumed. When no taxonomy exists, leave the field explicitly unassigned rather than inventing one.
67- **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.
68- **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).
69- **Near misses use the same skeleton** with Impact describing what would have happened, labeled as the counterfactual it is.
70
71The decision that often follows a postmortem (a new invariant, a policy change) is recorded via `recording-decisions` and linked, not embedded. Runbook updates that the incident exposed go through `writing-runbooks` in the same change as the fix, because documentation is part of done rather than a follow-up ticket.
riekelt