| name | post-mortem |
| description | Write engineering RCA record after bug is fixed. |
| origin | pi-crew |
| triggers | ["post-mortem","root cause","RCA","document this fix","close out bug"] |
post-mortem
The canonical engineering record of a bug fix. Written after debugging lands a real fix.
Required Inputs — Refuse to Draft Without These
If any missing → list what's missing and stop. Do not draft.
Structure
1. Summary
What broke (user terms), what fixed it (one sentence). JIRA key, PR, owner. A reader who stops here should have the right answer.
2. Symptom
Concrete: test output, error message, log line. No paraphrase. What was actually observed.
3. Root Cause
The actual bug mechanism. Code identifiers welcome — function names, file paths, branch conditions. Walk the cause chain end-to-end.
4. Why It Produced the Symptom
Walk the chain so reader connects symptom to cause. Often non-obvious — bug is in X but visible failure is in Y.
5. Fix
What changed and why this addresses root cause. Link to PR/commit. If a previous fix attempt papered over the symptom, name it and explain what was wrong.
6. How It Was Found
Short. The debugging path:
- What repro made it deterministic
- What tools cracked it
- Hypotheses tried and rejected (with one-line reason each)
- The single experiment that confirmed the cause
7. Why It Slipped Through
CI gap? Latent code? Workload gap? Incomplete prior fix? Review miss? Be specific.
If honest answer is "no good reason" — say so. Blameless — describe the gap, not the person.
8. Validation
How we know the fix works:
- Original failing test now passes (test name)
- Customer workload now completes (workload identifier)
- Other affected configs/workloads also tested
If only one config validated, say so explicitly.
9. Action Items
What + owner + tracking artifact:
- Regression test added at . (Owner, test name)
- CI gap closed: . (Owner, ticket)
- Doc/runbook updated. (Owner, link)
If none needed: "None — fix is sufficient and no class-of-bug follow-up warranted."
Tone
This is engineer-to-engineer:
- Code identifiers are first-class. Keep them — future engineers grep their way back.
- Mechanism over narrative. Walk the cause chain, don't soften.
- Blameless. Describe gaps and bugs, never people.
- No hedging. State it or don't write it.
Rules
- Never invent facts.
- Never strip code identifiers (they are the index).
- State validation coverage honestly.
- Get sign-off before posting to JIRA.