Discipline for handling difficult bugs. Only skip phases when the reason is clear.
Phase 1 — Build a feedback loop
This is the core of this skill. Everything else is mechanical process. If you have a fast, deterministic, agent-runnable pass/fail signal that covers this bug, you can find the cause; bisection, hypothesis-testing, and instrumentation all just consume this signal. Without it, staring at the code for any amount of time won't save you.
Invest a disproportionate amount of effort here.Be proactive. Be creative. Don't give up easily.
Ways to construct a feedback loop, tried in roughly this order
- Failing test, placed at a seam that can reach the bug, whether unit, integration, or e2e.
- Against a running dev server, Curl / HTTP script。
- With fixture input, CLI invocation, diff stdout against a known-correct snapshot.
- Headless browser script(Playwright / Puppeteer), drive the UI, and assert on DOM/console/network.
- Replay a captured trace. Save real network requests, payloads, or event logs to disk, and replay them in isolation against the corresponding code path.
- Throwaway harness. Start the minimal subset of the system (one service, mocked deps), and trigger the buggy code path with a single function call.
- Property / fuzz loop. If the bug is "sometimes outputs wrong results", run 1000 random inputs to find the failure pattern.
- Bisection harness. If the bug appears between two known states (commit, dataset, version), automate "start at state X, check, repeat", so that you can
git bisect run。 - Differential loop. Run old-version vs new-version (or two sets of configs) on the same input and diff the outputs.
- HITL bash script. Last resort. If a human must click, use
scripts/hitl-loop.template.shto drive the _human_, so the loop is still structured. The captured output is then fed back to you.
Build the right feedback loop, and the bug is already 90% fixed.
Iterate on the feedback loop itself
Treat the feedback loop as a product. Once you have _some_ loop, ask:
- Can I make it faster? (Cache setup, skip irrelevant init, narrow the test scope.)
- Can I make the signal sharper? (Assert on the specific symptom, not "it didn't crash".)
- Can I make it more deterministic? (Fix time, fix the RNG seed, isolate the filesystem, freeze the network.)
A 30-second flaky loop is only slightly better than no loop. A 2-second deterministic loop is a debugging superpower.
Non-deterministic bugs
The goal is not a clean reproduction, butincreasing the reproduction rate. Loop the trigger 100 times, parallelize, add pressure, narrow the timing windows, inject sleeps. A bug that flakes 50% of the time can be debugged; one that flakes 1% cannot. Keep increasing the reproduction rate until it is debuggable.
When you truly cannot build a loop
Stop and state this explicitly. List the approaches you tried. Ask the user for: (a) access to a reproducible environment, (b) captured artifacts (HAR file, log dump, core dump, timestamped screen recording), or (c) permission to add temporary production instrumentation.Do notcontinue hypothesising without a loop.
Do not enter Phase 2 until you have a trustworthy loop.
Phase 2 — Reproduce
Run the loop. See the bug appear.
Confirm:
- the loop produces thefailure mode described by the userdescribed by the user, not another nearby failure. Wrong bug = wrong fix.
- The failure can be reproduced across multiple runs; for non-deterministic bugs, the reproduction rate is high enough to debug from.
- You have captured the exact symptom (error message, wrong output, slow timing), and later phases can verify that the fix actually resolves it.
Do not proceed before reproducing the bug.
Phase 3 — Hypothesise
Before testing any hypothesis, first generate 3-5 ranked hypotheses. Generating only one hypothesis anchors you to the first plausible idea.
Each hypothesis must befalsifiable: state the prediction it produces.
Format: "If is the cause, then will make the bug disappear / will make it worse."
If you cannot state a prediction, the hypothesis is just a vibe. Drop it or tighten it.
Show the ranked list to the user before testing. They usually have domain knowledge and can instantly reorder it ("we just deployed the change from #3"), or know which hypotheses have already been ruled out. This checkpoint is cheap but saves time. Do not block here; if the user is AFK, continue with your ranking.
Phase 4 — Instrument
Every probe must map to a specific prediction in Phase 3.Change only one variable at a time.
Tool preferences:
- If the environment supports it, prefer Debugger / REPL inspection. One breakpoint beats ten logs.
- Add targeted logs。
- Never "log everything and grep".
Add a unique prefix to every debug log, for example [DEBUG-a4f2]. Final cleanup then becomes a single grep. Untagged logs stay; tagged logs disappear.
Perf branch. For performance regressions, logs are usually unsuitable. First establish a baseline measurement (timing harness,performance.now(), profiler, query plan), then bisect. Measure first, then fix.
Phase 5 — Fix + regression test
Write a regression test before the fix, but only if there is acorrect seam。
A correct seam means the test can reproduce thereal bug patternat the call site. If the only available seam is too shallow (the bug requires multiple callers but the test has only a single caller; the unit test cannot replicate the path that triggers the bug), a regression test there will create false confidence.
If there is no correct seam, that itself is a finding. Record it. The codebase architecture is preventing this bug from being locked down. Flag it for the next phase.
If a correct seam exists:
- Turn the minimised repro into a failing test at this seam.
- Watch it fail.
- Apply the fix.
- Watch it pass.
- Re-run the Phase 1 feedback loop against the original (unminimised) scenario.
Phase 6 — Cleanup + post-mortem
Before declaring completion, you must do:
- The original repro no longer reproduces (re-run the Phase 1 loop)
- Regression test passes (or no seam has been recorded)
- All
[DEBUG-...]instrumentation has been removed (grep the prefix) - Throwaway prototypes have been deleted, or moved to a clearly marked debug location
- Explain the final correct hypothesis in the commit / PR message, so the next debugger can learn from it
Then ask: what could have prevented this bug? If the answer involves an architecture change (no good test seam, tangled callers, hidden coupling), hand it over with specific information to the /improve-codebase-architecture skill. Suggestions should be raised after the fix lands, not before; you now have more information than you did at the start.