You are hunting a bug in code. The failure mode this skill prevents is the one every debugger falls into: reading code, forming a theory, and "fixing" the theory instead of the bug. The discipline: no hypothesis until a feedback loop exists. Skip phases only when you can say why.
Redact every secret in commands, outputs, and captured artifacts you show — write <REDACTED>; keep credentials in env vars, not in what you print. Quote only the lines of captured artifacts that carry signal.
Phase 1: Build the feedback loop (this IS the skill)
Everything else is mechanical. A tight pass/fail signal — one that goes red on this bug — makes bisection, hypothesis-testing, and instrumentation trivial. Without one, no amount of code-reading will save you. Spend disproportionate effort here.
Ways to construct one, in rough order of preference:
- 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 output against a known-good snapshot.
- Headless browser script driving the UI and asserting on DOM/console/network.
- Replay a captured trace — save a real request/payload/event log, replay it through the code path in isolation.
- Throwaway harness — a minimal subset of the system (one service, mocked deps) exercising the bug path with a single call.
- Property/fuzz loop — for "sometimes wrong output", run 1000 random inputs and hunt the failure mode.
- Bisection harness — bug appeared between two known states? Automate "boot at X, check" so
git bisect runcan consume it. - Differential loop — same input through old vs new version (or two configs), diff the outputs.
Once you have a loop, tighten it: faster (cache setup, narrow scope), sharper (assert the specific symptom, not "didn't crash"), more deterministic (pin time, seed RNG, isolate filesystem, freeze network). A 2-second deterministic loop is a debugging superpower; a 30-second flaky one is barely better than nothing.
Non-deterministic bugs: the goal is a higher reproduction rate, not a clean repro. Loop the trigger 100×, parallelise, add stress, inject sleeps to widen timing windows. A 50% flake is debuggable; 1% is not.
Phase 1 is complete when you can name ONE command you have already run at least once (show the invocation and output, redacted) that is:
- Red-capable — drives the actual bug path and asserts the user's exact symptom; it can go red on this bug and green once fixed.
- Deterministic — same verdict every run (or a pinned, high reproduction rate).
- Fast — seconds, not minutes.
- Agent-runnable — you can run it unattended.
If you catch yourself reading code to build a theory before this command exists — STOP. That is the exact failure this skill exists to prevent. If you genuinely cannot build a loop: say so explicitly, list what you tried, and ask the user for environment access, a redacted captured artifact (HAR, log dump, recording), or permission to add temporary instrumentation. Do NOT proceed to hypothesise without a loop.
Phase 2: Reproduce + minimise
Run the loop; watch it go red. Confirm it produces the failure the USER described — not a nearby different failure (wrong bug = wrong fix) — and capture the exact symptom for later verification.
Then minimise: shrink to the smallest scenario that still goes red. Cut inputs, callers, config, and steps one at a time, re-running after each cut. Done when every remaining element is load-bearing (removing any one goes green). A minimal repro shrinks the Phase 3 hypothesis space and becomes the Phase 5 regression test.
Phase 3: Hypothesise
Generate 3-5 ranked hypotheses before testing ANY of them — single-hypothesis generation anchors on the first plausible idea. Each must be falsifiable: "if X is the cause, then changing Y makes the bug disappear / changing Z makes it worse." Can't state the prediction? It's a vibe — discard or sharpen.
Show the ranked list to the user before testing — they often re-rank instantly ("we just deployed a change to #3") — but don't block on them; proceed with your ranking if they're away.
Phase 4: Instrument
Every probe maps to a specific Phase 3 prediction. One variable at a time.
- Prefer a debugger/REPL if the environment supports it — one breakpoint beats ten logs.
- Otherwise 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]) so cleanup is a single grep. Untagged logs survive into production; tagged logs die.
Performance regressions: logs are usually the wrong tool. Establish a baseline measurement first (timing harness, profiler, query plan), then bisect. Measure first, fix second.
Phase 5: Fix + regression test
Write the regression test BEFORE the fix — but only at a correct seam: one where the test exercises the real bug pattern as it occurs at the call site. A test at a too-shallow seam (unit test that can't replicate the triggering chain) gives false confidence.
If no correct seam exists, that itself is a finding — the architecture is preventing the bug from being locked down. Document it; don't fake the test.
With a correct seam: turn the minimised repro into a failing test → watch it fail → apply the fix → watch it pass → re-run the Phase 1 loop against the ORIGINAL un-minimised scenario.
Phase 6: Cleanup (required before declaring done)
- Original repro no longer reproduces (re-run the Phase 1 loop, show the output)
- Regression test passes — or the absence of a correct seam is documented
- All
[DEBUG-...]instrumentation removed (grep the prefix to prove it) - Throwaway harnesses/prototypes deleted
- The winning hypothesis stated in the commit/report, so the next debugger learns
Anti-patterns
- Hypothesising from code-reading before a red-capable loop exists.
- "Fixing" until the loop goes green without ever confirming the loop reproduced the USER's symptom.
- Shotgun instrumentation — untargeted logs that distinguish nothing.
- Declaring victory on the minimised repro without re-running the original scenario.
- Deleting or weakening the failing test to get green.
