writing-postmortems

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.]