debug

name	debug
description	Use when diagnosing a failure — a failing or flaky test, a stack trace, a crash, a CI or lint error — "why is this failing", "find the bug", "debug this", "it crashes when", "works on my machine". Not for writing new features or fixing a bug whose cause is already known (build).

Debug — Hypothesis Before Fix

Diagnose methodically. Each speculative edit moves the system from a known state to an unknown one; the harder the bug, the stricter the loop.

The loop

1. Reproduce. Make the failure happen on demand — ideally as a failing test. Can't reproduce → don't ship a speculative fix: add instrumentation to capture it next time, or ask for environment/input/steps, and say plainly that it isn't reproduced.
2. Isolate. Shrink to the smallest input that triggers it — binary-search the input; git bisect the history if it used to work.
3. Hypothesize testably. First read the error message word by word — it usually names the file, line, and cause. Then write 2–3 hypotheses in the form "the bug is at file:line because implies "; test the cheapest first.
4. Probe. One smallest experiment per hypothesis — a log line, an assertion, a narrowed test. One change at a time. Probes are temporary: remove them when done.
5. Fix at the root cause and verify. The stack trace points at the symptom; trace the wrong value upstream to where it originated and fix there. The regression test fails before the fix and passes after; re-run the full suite and the original reproduction. Intermittent bug → loop the test (e.g. 100×) before declaring victory.

Error-handling rule

When the user says "make it not crash" / "stop it taking down the server", they are asking you to make the failure survivable and detectable — never to suppress it. A fix where the operation silently looks like it succeeded (order unmarked, null nobody checks) is a worse bug than the crash. If the fix catches an error, the failure must stay detectable AND the affected state must stay consistent: log it, mark the affected record/operation as failed (not left half-done), and either raise a domain error a caller is expected to handle or return a result the caller checks. Test the failure path too — a test that only covers the happy path can't tell a fix from a swallow. A silent catch {} / return null / pass trades a loud crash for silent corruption — that is not a fix. The shape of a real catch: catch (e) { log.error(e); markFailed(record); return { ok: false, error: e }; } — and the caller checks it. Throwing a domain error (OperationFailedError) instead is right only when a caller is set up to catch it. If you find yourself typing catch {} or catch (e) { return null; }, delete it; that is the bug, not the fix.

When stuck (~1 hour, or the user says "still failing")

Never repeat a suggestion that was already tried — each next step must produce NEW information. For environment-specific failures (CI-only, prod-only, "works on my machine"): capture artifacts from where it fails (logs, recordings, core state), reproduce that environment locally, isolate the difference, or bisect. More sleeps and bigger timeouts are not diagnostics. If genuinely out of moves, stop: re-read the original report — are you debugging what was actually reported? — and hand off the note below filled in as far as you verifiably got, ending with the one question that would branch the search.

Right-sizing

An obvious one-line bug with an obvious cause doesn't need the full loop. But after two speculative edits with no traction, you are in a hard bug: return to step 1.

Delegated mode (running as a subagent)

Run the loop with the tools you have; return the note in one response, filled to wherever you verifiably got. A confirmed root cause without a fix is a valid result — say so.

Output — debugging note

## Bug: <one line>
Reproduction: <command or test that triggers it, or "NOT REPRODUCED: <why>">
Isolated to: <smallest input / commit range>
Hypotheses tested: <each → confirmed / rejected, with evidence>
Root cause: <file:line + why>
Fix: <the minimal change, at the cause not the symptom>
Regression test: <name; failed before fix, passes after>
Suite: <result verbatim>
Next: build (fix is nontrivial) | plan (it's a design flaw) | done

Checks

If you are about to…	Instead
Make a speculative edit "to see if it helps"	That's guess-and-check. Reproduce and hypothesize first.
Fix at the exact line the stack trace names	That's the symptom location; trace the bad value upstream.
Wrap the failing call in try/catch to make the error go away	You're hiding the bug. Diagnose first.
Declare an intermittent bug fixed after one green run	Loop the test before declaring victory.