Root Cause Debugger

When this fires

The default failure mode when fixing a bug is to patch whatever line the stack trace points at until the symptom disappears, without ever confirming that's actually the cause. That produces fixes that don't hold — the bug comes back in a different form, or the real cause is still live elsewhere. This skill forces a differential diagnosis: reproduce, form multiple hypotheses, gather evidence, and confirm the cause before writing a single line of fix.

Protocol

1. Reproduce it. Get the failure to happen on demand. If it can't be reproduced, say so explicitly and state what evidence you're working from instead (logs, a single report, a stack trace with no repro steps) — don't proceed as if you'd confirmed it.
2. Localize. Use git log / git blame / bisection against recent diffs to narrow where the behavior changed, especially for regressions. For failures with no clear recent change, localize by narrowing the reproduction (smallest input, smallest code path that still fails).
3. Form at least two hypotheses for the cause. A single hypothesis pursued immediately is exactly the symptom-patching this skill exists to prevent.
4. Gather evidence for and against each hypothesis — add logging, use a debugger, read the actual code path, check inputs/state at the failure point. Evidence must be observed, not assumed.
5. Verify the cause before writing any fix. The winning hypothesis should be one you can state as a mechanism: "X happens because Y, which causes Z" — not "it's probably something in this area."
6. Fix, then confirm the reproduction is gone. Re-run the exact reproduction from step 1. A fix that wasn't verified against the original repro isn't confirmed.

Hard rules

• Never write a fix before stating an evidence-backed root cause. "This might help" is not a root cause.
• If the cause can't be confirmed with available evidence, say so plainly instead of guessing and presenting the guess as diagnosed.
• A regression must be localized to a change (commit, dependency bump, config change) wherever the history makes that possible — "no idea when this started" is a last resort, not a first move.
• The fix must address the mechanism identified in step 5, not just make the visible symptom stop.

Output

Before any code is changed, state:

Reproduction: <exact steps/command, or "could not reproduce — working from: ...">
Localization: <commit/change/code path narrowed to, or "no clear recent change">
Hypotheses considered:
  1. <hypothesis> — <evidence for/against>
  2. <hypothesis> — <evidence for/against>
Root cause: <the confirmed mechanism, citing the evidence that confirmed it>

Then apply the fix, and report the reproduction re-run result (pass/fail) against the original repro from step 1.