Debug Diagnose

Debug & Diagnose

One-Liner

Build a fast, deterministic, agent-runnable pass/fail signal first — the bug is 90% fixed once you have that.

§ 1 · Core Philosophy

The critical insight: If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause. Without it, you are guessing.

Most debugging fails not because the engineer lacks knowledge, but because they skip directly to hypotheses without first establishing a reproducible signal. Build the loop, then let the loop drive everything else.

§ 2 · The Six Phases

Phase 1 — Build a Feedback Loop

Create the fastest reproducible test signal you can. Options in order of preference:

1. Unit test — isolates the exact failing condition
2. Integration test — exercises the real subsystem path
3. CLI script — passes known-bad input, asserts known-bad output
4. REPL session — interactive exploration to narrow the search space
5. Fuzz input — for non-deterministic or data-dependent failures

Key constraints:

• Must be runnable by the agent without human interaction
• Must produce pass/fail, not just "looks wrong"
• Must be deterministic (same input → same result)

Be aggressive and creative. Refuse to give up. A slow loop is better than no loop; a noisy loop can be narrowed.

Gate: You have a script/test that reproducibly demonstrates the failure.

Phase 2 — Reproduce

Run the loop and confirm it demonstrates exactly the reported failure — not a nearby issue, not a similar symptom.

If the loop shows a different failure than reported:

• You have found a second bug (note it, don't pursue it now)
• Continue narrowing until the loop matches the report precisely

Gate: Loop output matches the failure description word-for-word.

Phase 3 — Hypothesize

Before touching any code, generate 3–5 ranked hypotheses. Each must be:

• Falsifiable — a specific, testable prediction
• Ranked — order by likelihood given what you know
• Independent — don't let one hypothesis assume another is true

Write them down. Do not skip this step even if one hypothesis feels obvious — the obvious hypothesis is frequently wrong.

Phase 4 — Instrument

Test hypotheses in ranked order. For each:

1. Add targeted instrumentation at the relevant boundary (not blanket logging)
2. Use a debugger or tagged log output, not print-everywhere
3. Run the feedback loop
4. Does the output confirm or falsify the hypothesis?

Stop when one hypothesis is confirmed. Remove instrumentation from all falsified hypotheses immediately to keep signal clean.

Anti-pattern: Adding instrumentation for all hypotheses at once. You lose the ability to read the signal.

Phase 5 — Fix + Regression Test

1. Write a test at the appropriate architectural seam that fails because of the bug — before writing the fix
2. Implement the minimal fix
3. Confirm: feedback loop is now green, new regression test is green, existing tests still green
4. If the fix required touching more than one module, consider whether the modules should be decoupled

Phase 6 — Cleanup + Post-Mortem

1. Remove all debug instrumentation
2. Verify the feedback loop test is committed (it is now a permanent regression guard)
3. Document findings:
   • Root cause in one sentence
   • Why the bug was not caught earlier
   • What architectural change (if any) would prevent the class of bug

§ 3 · Quick Reference

Phase 1: BUILD THE LOOP (deterministic, agent-runnable, pass/fail)
Phase 2: REPRODUCE (confirm the loop shows exactly the reported failure)
Phase 3: HYPOTHESIZE (3-5 ranked, falsifiable hypotheses — written down)
Phase 4: INSTRUMENT (targeted, one hypothesis at a time)
Phase 5: FIX + REGRESSION TEST (test first, then fix)
Phase 6: CLEANUP + POST-MORTEM (remove debug code, document root cause)

§ 4 · When to Use This Skill

Use when:

• A bug is hard to reproduce or intermittent
• A performance regression appeared without obvious cause
• The same bug keeps recurring
• An agent is stuck in a "try random things" loop
• You need to present root cause analysis to stakeholders

Do NOT use when:

• The bug is a typo or trivially obvious from the error message
• You need to design a new feature (use to-prd)
• The codebase is unfamiliar — run zoom-out first

§ 5 · Relationship to Other Skills