Post-mortems
A Post-mortem is a written analysis of an incident or a recurring development-process issue, focused on root cause and prevention.
Two categories
| Category | Description |
|---|---|
| Service Incident | User-facing outages, regressions, or degraded behavior (the traditional scope) |
| Development Execution Issue | Not user-visible, but likely to recur and hurt the reliability, velocity, or correctness of development |
A development-execution post-mortem is warranted only when all three hold:
- Reproducible or systemic (not a one-off typo or local misconfig)
- Blocked or significantly delayed the planned work
- Preventable by a process, tooling, or environment change
Do not create one for one-off typos fixed immediately, already-documented known limitations, or issues affecting only one developer’s local setup with no recurrence risk.
Using it with AI agents
Ask your AI agent something like:
- “Analyze what went wrong and write a Post-mortem”
- “Register a Convention so this doesn’t happen again”
The agent analyzes the root cause and documents prevention measures. Reflect them as Conventions for rules agents must follow, or as development-environment, infrastructure, or process improvements otherwise.
The detail view shows the summary, category, action items, status, and the linked plan.
Structure
- Summary — what happened, in 1–2 sentences
- Category — Service Incident / Development Execution Issue
- Timeline — when and in what order (with timestamps)
- Root Cause — the causal chain, not surface symptoms
- Impact — who/what was affected and for how long
- What Went Wrong / Well — contributing factors / what limited the damage
- Prevention — concrete measures to prevent recurrence
Status
OPEN → IN_PROGRESS → RESOLVED
Good post-mortem vs bad post-mortem
| Good post-mortem | Bad post-mortem |
|---|---|
| Focuses on root cause | Only lists surface symptoms |
| Concrete prevention measures | ”We’ll be more careful” |
| Linked to a concrete change (convention, environment, infra) | Stays a document, nothing changes |
| System improvement, no blame | Points fingers |
Apply the prevention measures: turn them into convention rules, development-environment or infrastructure improvements, or process changes. For rules agents must follow, register them as Conventions so the same mistake isn’t repeated.