| name | debug |
| description | Systematic debugging methodology based on Zeller's scientific method. Reproduce, hypothesize, predict, test, isolate via binary search, fix root cause. Every fix gets a regression test. Triggers: bug, error, fix, broken, not working, fails, crashed, unexpected, stack trace, regression, exception. |
| allowed-tools | Read, Bash, Grep, Glob |
| kernel | {"kind":"methodology","version":1,"side_effects":"none","confirmation":"none"} |
Debugging is forming and testing a THEORY that explains the bug.
Not random changes. Not guessing. Scientific method applied to code.
DEFECT (in code) → INFECTION (in state) → FAILURE (visible symptom).
The failure you see is NOT where the bug is. Binary search upstream.
Systematic methodology beats ad-hoc guessing. The process is the multiplier.
Run agentdb recall with the exact error text, subsystem/library, failing
test, and known files/symbols. Recall again when the hypothesis changes or a new failure
appears; that is a new retrieval question. Reference on demand:
skills/debug/reference/debug-research.md.
1. **REPRODUCE**: get specific before touching code.
- Document: exact input, expected output, actual output (full stack trace), environment, frequency.
- "Sometimes fails" is not a reproduction. Get deterministic.
- (gate: can reproduce consistently, OR have added targeted logging to wait for next occurrence)
-
HYPOTHESIZE: list 3 causes before pursuing any.
- Read ALL error output first (anchoring bias mitigation).
- Write each hypothesis to AgentDB. Prevents circular re-investigation.
30+ min on one hypothesis with no evidence → abandon it. 3+ hypotheses rejected → step
back, re-examine assumptions. 2 failed fix attempts → invoke tearitapart; it may be a
design problem. Repeated failed corrections in one session → /clear with a minimal
reproduction. Bug only in production → add targeted monitoring, document, move on.
For 3+ plausible causes, spawn one fresh-context agent per hypothesis (evidence_for /
evidence_against / confidence); fresh context catches what a long session anchors past.
