post-mortem

name	post-mortem
description	Write the canonical engineering record of a fixed bug — root cause, mechanism, fix, validation, and how it slipped through. Trigger on /post-mortem, when asked for RCA/root cause analysis, or after a debug session lands a validated fix.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash, Edit

Post-mortem

Write the engineering record after debugging lands a real fix. Engineer audience — code identifiers welcome.

Required Inputs — Refuse to Draft Without These

• Reliable repro exists (deterministic or high-rate flake).
• Root cause is known (mechanism identified, not hypothesis).
• Fix is identified (PR/commit/branch pointer).
• Fix is validated (original repro now passes).

List what's missing and stop if any are absent.

Structure

1. Summary (mandatory)

What broke, in user/workload terms. What fixed it. JIRA key, PR, owner.

2. Symptom

What was actually observed — error message, test output, log line, perf number.

3. Root cause (mandatory)

Actual bug mechanism. Walk the cause chain end-to-end. Code identifiers expected: function names, file paths, branch conditions, commit SHAs.

4. Why it produced the symptom

Link root cause to symptom. Often non-obvious — walk the chain so a reader who only knows the symptom can connect it to the cause.

5. Fix (mandatory)

What changed and why this addresses the root cause, not the symptom. Link to PR/commit.

6. How it was found

Repro approach, tools that cracked it, hypotheses rejected (one-liner why), experiment that confirmed the cause.

7. Why it slipped through

CI gap, latent code, workload gap, incomplete prior fix, review miss. Blameless — describe the gap, not the person.

8. Validation (mandatory)

Concrete: test name, workload run link, perf numbers. State coverage honestly — "validated on X config; not retested on Y."

9. Follow-ups

Action items with owner and tracking artifact. If none, say so explicitly.

Rules

• Refuse to draft without all four required inputs.
• Never invent root cause, owner, validation runs, or action items.
• Never strip code identifiers — they are the index.
• Blameless — describe gaps and bugs, never people.
• State validation coverage honestly.

Experience Log

This skill learns from experience. Mechanism:

• Read .claude/experience/post-mortem.md at skill start to benefit from past lessons.

• Write to .claude/experience/post-mortem.md after use if you learned something new.

• Format: YYYY-MM-DD: <lesson> — one line per entry.

• Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.

This skill improves over time. After each use, append lessons learned.

Record format: YYYY-MM-DD: <lesson> Read this at skill start to apply past lessons.