| type | skill |
| lifecycle | stable |
| inheritance | inheritable |
| name | postmortem |
| description | Write a postmortem for a regression or incident that escaped to production, broke real users, and traces back to a design flaw worth documenting. Use when asked to "write a postmortem", "document an incident", "analyze a production failure", "root cause analysis", or "incident review". Only invoke after confirming no existing postmortem covers the same root cause. |
| applyTo | **/*incident*,**/*postmortem*,**/*outage* |
| tier | standard |
| currency | 2026-04-22T00:00:00.000Z |
Postmortem Writing
Structured analysis of production incidents to capture root causes, prevent recurrence, and build organizational knowledge.
When to Invoke
All must be true:
- Production escape — the bug shipped in a released artifact
- User-visible breakage — real users hit it
- Non-obvious root cause — traces to a design assumption, invariant violation, or interaction between independently-correct changes
- Not already documented — search the project's existing postmortem directory first
Do NOT write a postmortem for: typos, simple bugs caught by CI, issues where the fix is obvious from the diff, incidents without user impact.
Before Writing
Answer these questions by investigating the codebase, PRs, and release history:
| Question | Why It Matters |
|---|
| How did the bug reach users? | Trace: which PR, which release, why CI didn't catch it |
| What made it hard to diagnose? | Misleading errors? Symptom far from cause? |
| What design assumption was violated? | Every qualifying postmortem has one — name it |
| What would have prevented it? | This becomes the actionable outcome |
Template
Detect the project's postmortem directory (commonly docs/postmortems/ or equivalent). Name: regression-<short-description>.md.
# Postmortem: [Brief Title]
## Summary
2-3 sentences: what broke, who was affected, root cause.
## Error Manifestation
What users saw. Include: exact error/behavior, affected environments, impact scope, misleading symptoms.
## Root Cause
The design assumption that was violated. High-level enough for someone unfamiliar.
## Why It Escaped
How it got past review, CI, and testing. Be specific — name the gap, not "testing was insufficient."
## Fix
What changed and why it restores the invariant. Link to PR/commit.
## Timeline
| Date | Event |
| ------ | --------------------- |
| [date] | PR introduced the bug |
| [date] | Release shipped |
| [date] | First user report |
| [date] | Root cause identified |
| [date] | Fix released |
| Action | Type | Status |
| ----------------- | -------------------- | ------ |
| [specific action] | Test/CI/Process/Docs | ✅/☐ |
