debug

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)

2. 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.