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), after a defect that reached users, and after a near miss: a guard that caught what review missed is the cheapest lesson available and earns the same write-up. Do NOT invoke during the live incident (the runbook governs that), for assigning accountability (a postmortem that needs a person's name to make sense is describing a process hole), or for a status update to stakeholders (that is a report, not a postmortem).

Skeleton

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