/incident-readout

name: incident-readout
description: Use when a bug fix or complex debugging session concludes and a blameless post-mortem summary is needed for human review.

Purpose

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.

When to Use

• 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

Inputs

• The fix (diff or commits) and the debugging context from the session
• The related PR or issue, if one exists

Workflow

1. **Reconstruct the facts from history** — pull them from the repo rather than recalling them:

   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:

   ### 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.