Use this loop for uncertain or hard-to-reproduce bugs and performance regressions. Scale the investigation to the uncertainty. When a trace, failing test, or direct code evidence already establishes the cause, apply the authorized narrow fix and verify the original symptom; do not manufacture extra hypotheses or minimise a repro that already isolates the fault.
When exploring the codebase, read CONTEXT.md (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
Phase 1 — Build a feedback loop
This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug — one that goes red on this bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
Invest enough to distinguish the reported failure from nearby symptoms. Timebox unsuccessful approaches; switch methods or identify missing evidence rather than repeating unproductive attempts.
Ways to construct one — choose the smallest suitable method
- Failing test at whatever seam reaches the bug — unit, integration, e2e.
- Curl / HTTP script against a running dev server.
- CLI invocation with a fixture input, diffing stdout against a known-good snapshot.
- Headless browser script (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
- Replay a captured trace. Save a real network request / payload / event log to disk; replay it through the code path in isolation.
- Throwaway harness. Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
- Property / fuzz loop. If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
- Bisection harness. If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can
git bisect runit. - Differential loop. Run the same input through old-version vs new-version (or two configs) and diff outputs.
- HITL bash script. Last resort. If a human must click, drive them with
scripts/hitl-loop.template.shso the loop is still structured. Captured output feeds back to you.
A useful feedback loop makes competing explanations easier to distinguish.
Tighten the loop
Treat the loop as a product. Once you have a loop, tighten it:
- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
Non-deterministic bugs
Seek a measurable reproduction rate. Bounded repetition, controlled stress, or timing instrumentation can help; keep load within an authorized test environment and report attempts and observed failures. A rare failure remains evidence even when its rate cannot be increased.
When you cannot build a loop yet
Say so explicitly and list what you tried. Request the smallest missing artifact or access that would make reproduction possible. Meanwhile, continue useful read-only work: inspect logs and traces already available, follow the static code path, compare recent changes, and form evidence-ranked hypotheses. Label these as unverified until a runnable signal exists. Adding production instrumentation still requires authorization.
Completion criterion — a tight loop that goes red
Phase 1 is done when the loop is tight and red-capable: you can name one command — a script path, a test invocation, a curl — that you have already run at least once (paste the invocation and its output), and that is:
- Red-capable — it drives the actual bug code path and asserts the user's exact symptom, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to catch this specific bug.
- Deterministic — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
- Fast — seconds, not minutes.
- Agent-runnable — you can run it unattended; a human in the loop only via
scripts/hitl-loop.template.sh.
Do not claim Phase 1 complete without this command. If the environment prevents a red-capable command, use the evidence-only path above rather than pretending the bug has been reproduced.
Phase 2 — Reproduce + minimise
Run the loop. Watch it go red — the bug appears.
Confirm:
- The loop produces the failure mode the user described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
- The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
- You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
Minimise
When extra inputs obscure the cause, shrink the repro to a scenario that isolates the failure. Cut inputs, callers, config, data, and steps one at a time, re-running the loop after each cut — keep only what's load-bearing for the failure.
Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
Stop shrinking when the repro isolates the suspected cause and supports a meaningful regression check. Further minimisation is useful only if it can change the diagnosis.
Prefer a reproduced failure before fixing. If reproduction is unavailable but direct evidence establishes the defect, an authorized narrow fix can proceed with focused checks; clearly state that the original runtime symptom remains unverified. If the cause is uncertain, collect discriminating evidence before changing behavior.
Phase 3 — Hypothesise
Rank the plausible causes supported by current evidence. Test the leading cause directly when the evidence is strong; add competing hypotheses when ambiguity remains or the first prediction fails. Do not fill a quota.
Each hypothesis must be falsifiable: state the prediction it makes.
Format: "If is the cause, then will make the bug disappear / will make it worse."
If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
Share the leading hypothesis and next discriminating check when useful. Ask only for missing context that materially changes the investigation; routine testing needs no user checkpoint.
Phase 4 — Instrument
Each probe must map to a specific prediction from Phase 3. Change one variable at a time.
Tool preference:
- Debugger / REPL inspection if the env supports it. One breakpoint beats ten logs.
- Targeted logs at the boundaries that distinguish hypotheses.
- Never "log everything and grep".
Tag every debug log with a unique prefix, e.g. [DEBUG-a4f2]. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
Perf branch. For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, performance.now(), profiler, query plan), then bisect. Measure first, fix second.
Phase 5 — Fix + regression test
Write the regression test before the fix — but only if there is a correct seam for it.
A correct seam is one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
If no correct seam exists, that itself is the finding. Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
If a correct seam exists:
- Turn the minimised repro into a failing test at that seam.
- Watch it fail.
- Apply the fix.
- Watch it pass.
- Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
Phase 6 — Cleanup + post-mortem
Required before declaring done:
- Original repro no longer reproduces (re-run the Phase 1 loop)
- Regression test passes (or absence of seam is documented)
- All
[DEBUG-...]instrumentation removed (grepthe prefix) - Throwaway prototypes deleted (or moved to a clearly-marked debug location)
- The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
Then ask: what would have prevented this bug? If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the /improve-codebase-architecture skill with the specifics. Make the recommendation after the fix is in, not before — you have more information now than when you started.