postmortemlisted

# Postmortem A **postmortem** is a backward-looking record of a failure: what broke, the mechanism, why every safety net missed it, and the concrete guardrails added so the same class of bug fails loudly next time. It is the complement of [decision-records](./decision-records.md), which records a forward-looking decision and its alternatives. **The defining constraint:** a postmortem is retrospective and failure-specific — it is not an incident log, not a blame report, and not an ADR. Its job is to make the *mechanism* explicit and to leave guardrails, so the next occurrence fails loudly instead of silently. ## When one is owed Write a postmortem when a bug is: - **Subtle** — the mechanism is non-obvious and a careful engineer would re-derive it the hard way; - **Systemic** — the reason it escaped every safety net is structural, not a one-line mistake; - **Costly to rediscover** — it cost real debugging time, and would cost it again. A trivial one-line fix with an obvious cause does not earn one. When unsure, ask whether the next engineer would hit the same wall — if yes, write it. ## Structure Open with an **Executive summary**: one short paragraph a busy reader absorbs in thirty seconds — what broke, the root cause in plain terms, why it escaped, and the durable lesson. Then the detail: 1. **Summary** — what happened, in plain terms. 2. **Timeline** — the sequence that led to the failure and its discovery. 3. **Root cause** — the mechanism, stated precisely, not th