Systematic Debugging

---
name: "systematic-debugging"
description: "A disciplined procedure for finding root causes -- reproduce, isolate, hypothesize, bisect, fix, verify. Consult when a bug is non-obvious, a fix didn't hold, or you've tried the same thing twice without progress."
user-invocable: false
---

# Systematic Debugging

When stuck, stop guessing. Run the loop. Random edits that "might fix it"
waste turns and mask the real cause. For known tool/git/CI failures, check the
Error Patterns skill first — this skill is for novel bugs.

## The Loop

1. **Reproduce.** Get a reliable, minimal repro before changing anything. A bug
   you cannot reproduce on demand, you cannot confirm fixed. Note the exact
   command, inputs, and expected-vs-actual.
2. **Isolate.** Shrink the surface. Remove inputs, comment out code, halve the
   data until the smallest thing that still fails remains. `git bisect` when a
   regression has a known-good past commit.
3. **Hypothesize.** State ONE specific, falsifiable cause: "X is null because Y
   runs before Z." If you cannot name a mechanism, you are still guessing.
4. **Test the hypothesis.** Add a log/breakpoint/assertion that the hypothesis
   predicts. Observe. Confirm or kill it before touching the fix.
5. **Fix the root cause.** Not the symptom. If the fix is "add a null check,"
   ask why it is null — that is usually the real bug.
6. **Verify.** Re-run the repro from step 1. Then run the surrounding tests to
   confirm you broke nothing. A fix unconfirmed against the original repro is
   not a fix.

## Discipline

- **Read the actual error.** Full message, full stack trace, top to bottom. The
  answer is in there more often than not. Don't skim to the first familiar line.
- **One change at a time.** Change-everything-and-pray destroys the signal about
  what actually mattered. Revert failed experiments before the next one.
- **Trust nothing, verify everything.** Don't assume which function runs, what a
  variable holds, or that a dependency is installed. Add the log and look.
- **Bisect over speculation.** When a thing used to work, the diff that broke it
  is findable mechanically. Don't theorize about a regression you can bisect.
- **Question the assumption, not just the code.** If reality contradicts your
  mental model, the model is wrong. Find which assumption is false.

## Stop conditions

- Same approach twice with no new information -> stop, change technique, or
  escalate. Repeating a failed action is Error #-class behavior.
- Fix doesn't hold after verify -> the hypothesis was wrong. Return to step 3
  with what you just learned. Do not pile a second guess on top.
- Root cause genuinely unclear after the loop -> surface what you ruled out and
  what remains, and ask. A documented dead end beats a silent wrong fix.