Root Cause Debugger

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.

1. 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).

1. Form at least two hypotheses for the cause. A single hypothesis

pursued immediately is exactly the symptom-patching this skill exists to prevent.

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

1. 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."

1. 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: 
Localization: 
Hypotheses considered:
  1.  — 
  2.  — 
Root cause: 

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pinexai
• Source: pinexai/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.