systematic-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# Systematic Debugging

Use when the user reports a bug, a test fails unexpectedly, or output doesn't match expectations.

## Loop

1. **Reproduce.** Get a reliable, minimal repro. If you can't reproduce it, that's step 1 — don't theorize past an unreproducible bug.
2. **Observe.** Read the actual error, stack trace, and surrounding state. No assumptions.
3. **Hypothesize.** State *one* specific cause. "It might be X" — name X concretely.
4. **Test the hypothesis.** Add a print, read a related file, run a smaller version. Confirm or kill the hypothesis with evidence.
5. **Loop.** If killed, form a new hypothesis. Do not patch on a guess.
6. **Fix the root cause, not the symptom.** If the fix is "wrap in try/except and continue", stop — you found a symptom.
7. **Add a regression test** before closing out (pair with `test-driven-development`).

## Anti-patterns

- "Let me try a few things" — that's guessing, not debugging.
- Patching one site of failure when the root cause is upstream.
- Disabling a failing test to make CI green.
- Claiming a fix without reproducing the original bug *and* showing it's gone.

## Handoff

Always finish with `verification-before-completion`: re-run the original repro, the new regression test, and the broader suite.

From krone9/pi-superpowers, MIT.

More from krone9/pi-superpowers