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, 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: