incident-readout · diff
git:20260502.c974828 to git:20260606.8653d0e
55 added, 13 removed. Audit A to A.
---
name: incident-readout
- description: "Use after fixing a bug to generate a blameless post-mortem summary for human review."
+ description: Use when a bug fix or complex debugging session concludes and a blameless post-mortem summary is needed for human review.
---
- # Incident Readout
+ ## Purpose
- When a complex debugging session ends, you must produce an incident readout. This prevents knowledge loss and helps humans review the fix quickly.
+ When a complex debugging session ends, produce an incident readout. This prevents knowledge loss and helps humans review the fix quickly. Keep it blameless: causes and prevention, not people.
- ## Format
+ ## When to Use
- Output an `incident-readout.md` (or print to terminal) using this structure:
+ - A bug fix landed after a non-trivial debugging session
+ - An incident is resolved and needs a reviewable summary
+ - Session knowledge would otherwise be lost at handoff
- ### 1. The Symptom
- What was reported? (1-2 sentences)
+ ## Inputs
- ### 2. The Root Cause
- What was the actual underlying technical reason for the failure? Be highly specific about the exact line of code, assumption, or state that failed.
+ - The fix (diff or commits) and the debugging context from the session
+ - The related PR or issue, if one exists
- ### 3. The Fix
- What did we change to fix it? Provide a high-level summary of the structural change, not just a diff.
+ ## Workflow
- ### 4. Prevention
- How do we ensure this never happens again? (e.g., "Added test case X", "Refactored module Y to be strongly typed").
+ 1. **Reconstruct the facts from history** — pull them from the repo rather than recalling them:
+
+ ```bash
+ git log --oneline -10 # the fix commits
+ git show <fix-commit> --stat # what the fix touched
+ gh pr view <number> --json title,body,comments # if a PR exists
+ ```
+
+ 2. **Fill the readout structure.** Output an incident readout document (or print to terminal) using this structure:
+
+ ```markdown
+ ### 1. The Symptom
+ What was reported? (1-2 sentences)
+
+ ### 2. The Root Cause
+ What was the actual underlying technical reason for the failure? Be highly
+ specific about the exact line of code, assumption, or state that failed.
+
+ ### 3. The Fix
+ What did we change to fix it? Provide a high-level summary of the
+ structural change, not just a diff.
+
+ ### 4. Prevention
+ How do we ensure this never happens again? (e.g., "Added test case X",
+ "Refactored module Y to be strongly typed").
+ ```
+
+ ## Output
+
+ - A four-section readout (Symptom / Root Cause / Fix / Prevention), as a document or terminal output
+
+ ## Verification
+
+ - [ ] Root cause names the specific line, assumption, or state — not a vague area
+ - [ ] Fix described structurally, not as a pasted diff
+ - [ ] Prevention is a concrete action, not "be more careful"
+ - [ ] Claims cross-checked against the actual commits/PR, not memory
+
+ ## Failure Modes
+
+ - **Symptom-as-cause** — restating the error message in the Root Cause section.
+ - **Diff dumping** — pasting the patch where a structural summary is needed.
+ - **Empty prevention** — "fixed it" without a regression test or structural guard.
+