Debug (Pocock alternative)
Alternative to default debug.
Iron law
No hypothesis until you have a tight loop that can go red on this exact symptom. Run the loop command once and show its output before the first hypothesis.
Phases
- Loop — failing test, curl, CLI fixture, headless script, replay, harness, fuzz, bisect, or differential. Tighten: faster, sharper assert, more deterministic. Flakes: raise repro rate until debuggable. Cannot build a loop → stop, list tries, ask the operator.
- Reproduce + minimise — same failure the user named. Shrink until every remaining piece is load-bearing.
- Hypothesise — 3–5 ranked, each falsifiable (“If X, then changing Y …”). Show the list; don’t block if the operator is AFK.
- Instrument — one variable; debugger over log-spam. Tag logs
[DEBUG-xxxx]so cleanup is one grep. Perf: measure first. - Fix — failing test at a real seam (
tdd), then fix, then re-run the original loop. No correct seam → that is the finding; do not fake a shallow test. - Cleanup — loop green, tagged logs gone, throwaways gone, winning hypothesis in the commit/PR.
Always
Redact secrets in anything you show (<REDACTED>). Credentials stay in env, not in the log you paste.
Never
- Load with
debugordebug-anthropic. - Copy
scripts/from upstream. - Hypothesise from reading code with no red-capable command.
Upstream
Rewrite of mattpocock/skills skills/engineering/diagnosing-bugs @ 74ca5fe077456a0b3b2f5310cf9430999fd0b5fd (MIT). See SOURCES.md.