Diagnosing Bugs

A discipline for hard bugs. Skip phases only when explicitly justified.

Phase 1 — Build a feedback loop

This is the skill. If you have a tight pass/fail signal that goes red on the bug, you will find the cause. Without one, no amount of staring at code helps.

Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.

Ways to construct a feedback loop (roughly in order of preference):

1. Failing test (unit, integration, e2e)
2. Curl / HTTP script against a running dev server
3. CLI invocation with a fixture input, diffing stdout against known-good
4. Headless browser script (Playwright/Puppeteer)
5. Replay a captured trace (network request replayed in isolation)
6. Throwaway harness (minimal subset of system, mocked deps)
7. Property / fuzz loop (1000 random inputs for "sometimes wrong" bugs)
8. Bisection harness (automate git bisect run)
9. Differential loop (old-version vs new-version, diff outputs)
10. HITL bash script (last resort — human watches, confirms pass/fail)

Then tighten the loop: make it faster, make the signal sharper (assert the specific symptom), make it more deterministic.

For non-deterministic bugs: raise the reproduction rate (loop 100x, parallelise, add stress). A 50%-flake is debuggable; 1% is not.

Completion criterion: one command that is red-capable, deterministic, fast (seconds), and agent-runnable. You must have already run it at least once and pasted the output.

If you catch yourself reading code to build a theory before this command exists, STOP.

Phase 2 — Reproduce + minimise

Run the loop, confirm it produces the user's exact failure mode. Then shrink the repro to the smallest scenario that still goes red — cut inputs, callers, config, steps one at a time, re-running after each cut.

Done when every remaining element is load-bearing.

Phase 3 — Hypothesise (PAUSE FOR USER)

Generate 3–5 ranked hypotheses before testing any. Each must be falsifiable: "If [X] is the cause, then [action] will make the bug disappear / worse."

Show the ranked list to the user before testing. This is the HITL pause point in the wayfinder flow — the user confirms which hypotheses to test first, or adds their own.

Phase 4 — Instrument

Each probe maps to a specific prediction from Phase 3. Change one variable at a time.

Tool preference:

1. Debugger / REPL
2. Targeted logs
3. Never "log everything and grep"

Tag every debug log with a unique prefix: [DEBUG-a4f2]. This makes cleanup in Phase 6 trivial.

For performance regressions: measure first (baseline timing / profiler / query plan), then bisect.

Phase 5 — Fix + regression test

1. Write the regression test before the fix (if a correct seam exists)
2. Watch it fail
3. Apply the fix
4. Watch it pass
5. Re-run the Phase 1 loop to confirm the original repro is green

If no correct seam exists for a regression test, that itself is the finding — flag it for architecture improvement (Phase 6).

Phase 6 — Cleanup + post-mortem

Required:

• Original repro no longer reproduces
• Regression test passes (or absence of seam documented)
• All [DEBUG-...] instrumentation removed (grep the prefix)
• Throwaway prototypes/harnesses deleted
• Hypothesis that was correct stated in commit/PR message

Then ask: "What would have prevented this bug?"

If the answer is architectural (no good seam, coupling, shallow module), create a new wayfinder ticket pointing to improve-codebase-architecture for a deepening review.

What this skill must never do

• Never skip Phase 1 (the feedback loop) — reading code without a repro is guessing
• Never test multiple hypotheses simultaneously
• Never leave debug instrumentation in committed code
• Never declare "fixed" without re-running the original repro command