Read a real skill before you buy anything.

---
name: systematic-debugging
description: Use when encountering any bug, test failure, crash, or unexpected behavior — before proposing or attempting any fix.
keywords: ["debug", "bug", "test failure", "crash", "reproduce", "root cause"]
---

# Systematic Debugging

Debugging is a search problem. Guessing is the slowest search algorithm.
This procedure is mandatory for every bug, no matter how obvious the cause
appears — *especially* then, because "obvious" causes are where wrong fixes
come from.

## The procedure

1. **Reproduce.** Make the failure happen on demand, in the smallest case
   you can construct. A bug you can't reproduce is a bug you can't verify
   you fixed.
   - *Gate: no hypotheses, no fixes, no code changes until this step is done.*
2. **Capture the evidence.** Exact error text, stack trace, failing input,
   expected vs. actual. Write it down before touching anything — the crime
   scene degrades as you work.
3. **Isolate.** Shrink the search space by bisection: halve the input, the
   commit range, the config, or the code path, and re-test. Repeat until the
   trigger is pinned to one variable.
4. **Hypothesize — one at a time.** State the suspected cause as a sentence
   that could be false. Design the cheapest test that would falsify it.
   Run it. Record the verdict before forming the next hypothesis.
5. **Fix at the root.** Fix the cause, not the symptom. If the fix is in a
   different place than the error appeared, explain why in one sentence.
6. **Prove it.** The reproduction from step 1 now passes; the rest of the
   test suite still passes. Where practical, the reproduction becomes a
   permanent regression test.
7. **Log the lesson.** One paragraph — root cause, fix, and the class of
   bug — appended to the project's debugging notes (or the PR description).

## Red flags — stop, you're rationalizing

- "The cause is obvious, I'll just fix it." (Then reproduction takes 30
  seconds and costs you nothing.)
- "I can't reproduce it, but this fix should cover it."
- "Let me try changing this and see what happens." (That's a hypothesis —
  state it and test it properly.)
- Editing code while the reproduction is still unwritten.
- Third fix attempt for the same symptom. (You're guessing. Return to
  step 3 — the bug is not where you think it is.)

## When reproduction is genuinely impossible

Intermittent production-only failures exist. Then the procedure adapts, not
dissolves: instrument (add the logging you wish you had), narrow the trigger
statistically, and ship the fix behind evidence that it addresses the only
remaining suspect — stated explicitly as a probabilistic fix, never as "fixed."