debug-root-cause

name	debug-root-cause
description	Force real debugging before fixing. Reproduce, trace the failing path, identify the first wrong state, explain root cause before editing. Trigger on /debug-root-cause, when a bug is reported, a test fails, or something is throwing/breaking.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash, Edit

Debug Root Cause

Four-step debugging discipline. Apply in order before proposing any fix.

1. Reproduce reliably

• Deterministic repro — capture exact steps, inputs, environment as a runnable artifact (test, script, CLI invocation).
• Flaky repro — raise the rate first: loop, parallelize, add stress, narrow timing windows. 50% flake is debuggable; 1% is not.
• No repro — stop. Say so explicitly. Do not hypothesize without a repro.
• Target: a fast (1-5s), deterministic pass/fail signal.

2. Trace the fail path

Find where the code breaks and what stops it from breaking. Order:

1. Debugger — if supported, attach and step to failure site. One breakpoint beats ten logs.
2. Source trace + knob enumeration — trace the code path end-to-end. List every config flag, env var, branch condition, input shape, timing factor that can influence the outcome.
3. Instrumentation — add tagged log statements ([DBG-<tag>]) at suspected sites. Let traces show where reality diverges from your mental model.

3. Identify root cause

• Walk the cause chain end-to-end. Does it explain all symptoms?
• Generate 2-3 ranked hypotheses, not one. Single-hypothesis thinking anchors on the first plausible idea.
• Design the experiment that would disprove each hypothesis. Run the disproof first.
• Identify the first wrong state — the earliest point where reality diverges from correctness.

4. Fix and verify

• Only after steps 1-3 are satisfied.
• Do not add random null checks, try/catch wrappers, sleeps, retries, or test weakening.
• Add regression coverage when practical.
• If only mitigation is possible, label it explicitly as temporary.

Operating Rules

• Do not propose a fix before step 1 is satisfied.
• Do not test hypotheses before step 2 has narrowed the path.
• Do not commit to a hypothesis before step 3 has tried to disprove it.
• If you catch yourself proposing a fix without a reliable repro, stop and return to step 1.

Experience Log

This skill learns from experience. Mechanism:

• Read .claude/experience/debug-root-cause.md at skill start to benefit from past lessons.

• Write to .claude/experience/debug-root-cause.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.