Skip to content

6.3 Debug: When Things Break

Things break. A disciplined method can make debugging more reviewable: gather evidence, act on a hypothesis, and verify the fix. This lesson gives you that method and a way to evaluate an agent's contribution.

What you will learn

  • Run the four-step debug method: reproduce, isolate, fix, prove.
  • Brief a debugging session so the agent hunts causes instead of guessing patches.
  • Escape the two classic traps: the fix-that-isn't and the death spiral.

Builder principle

Never let anything be fixed until it's been reproduced and proven. Everything between those two is negotiable.

The method

Step 1 — Reproduce

Before any fixing: make the bug happen on demand. A bug you can trigger reliably is already half-caught; a bug you can't reproduce can't be verified fixed — you'd be shipping hope.

The debug brief starts here, and precision is everything:

BUG: the contact form clears itself when submitted, and no email arrives.
REPRODUCE: open the live site on mobile Safari, fill all three fields,
tap Send. Fields clear; no confirmation appears; nothing in inbox.
EXPECTED: confirmation message + email within a minute.
WORKS: same steps on desktop Chrome work fine.
Reproduce this first — confirm you can trigger it before proposing anything.

That WORKS: line is disproportionately valuable — the difference between the broken and working paths points a searchlight at the cause.

Step 2 — Isolate

Now the agent earns its keep — hypothesis-driven narrowing:

List your top 3 hypotheses for the cause, ordered by likelihood.
Then check them one at a time with evidence — logs, code reading,
targeted tests. Show me the evidence that confirms or kills each one.
Don't change any behavior yet.

The one at a time, with evidence, no fixes yet framing matters. It converts the agent from a pattern-matcher blurting the statistically-likely patch into an investigator — and it produces a paper trail you can follow and challenge in plain language.

Step 3 — Fix

Cause confirmed → smallest change that addresses the cause, not the symptom:

Confirmed: hypothesis 2. Make the minimal fix for that cause.
Don't refactor anything else while you're in there.

Step 4 — Prove

The fix isn't real until the original reproduction fails to reproduce:

Run the exact REPRODUCE steps from the start. Show me it now behaves
as EXPECTED. Then check the neighborhood: does desktop still work?
Do the other forms still submit?

Reproduce → isolate → fix → prove. Same shape every time, from a broken button to a production outage.

The two traps

The fix-that-isn't. The agent declares victory; the bug returns Thursday. Root cause: step 4 got skipped, or "proved" meant the agent's assertion rather than the original reproduction re-run. The method's whole architecture exists to make this impossible — the reproduction from step 1 is the only accepted proof.

The death spiral. Attempt three doesn't work. Attempt four re-breaks attempt two's progress. The window is now full of failed patches, and the agent is pattern-matching against its own debris. You know this one from 5.5 — context pollution. The escape:

1. STOP. Inspect `git status --short` and `git diff`; restore only the tracked paths you mean to discard, or return to a reviewed checkpoint using your team's normal Git workflow.
2. /wrap — but for debugging: have it write docs/bug-notes.md —
   symptom, hypotheses killed (with evidence), hypotheses untested.
3. /clear
4. Fresh session: "Read docs/bug-notes.md. Continue the investigation
   from hypothesis 3 — 1 and 2 are ruled out."

A clean window + a distilled case file beats an hour of accumulated flailing, every time. Knowing when to pull this cord — around the third failed attempt — is a genuine skill marker.

You bring more to debugging than you think: you are the reproduction machine. Precise observations — what you did, what you saw, what you expected, where it works — are the highest-value input in the whole method, and they require zero code. Write the BUG/REPRODUCE/EXPECTED/WORKS block carefully and the agent does the rest. Vague bug reports are the actual beginner mistake, not missing code knowledge.

Two upgrades. First: make the reproduction executable — step 1's output should be a failing test whenever possible; then step 4 is pytest green plus the relevant suite staying green. The regression test reduces recurrence risk but does not prove the whole system is defect-free. Second: for production issues, the gather phase starts in logs and telemetry. Before providing any slice to an agent, classify it, confirm authorization and provider handling, remove credentials and unnecessary personal or customer data, and use synthetic logs when those checks are unclear. Then provide only the minimum relevant lines. Direct evidence is useful context, but extra sensitive evidence is still extra exposure.

Try it now

Debug something real, method strictly followed:

  1. Find or make a bug — break something in your quick-win deliberately if life hasn't provided one (change a filename a link depends on; future you: this is a great exercise).
  2. Write the four-line bug block before opening a session — BUG / REPRODUCE / EXPECTED / WORKS.
  3. Run the method: reproduce → 3 hypotheses with evidence → minimal fix → prove with the original reproduction.
  4. Journal: at which step did the cause reveal itself, and what evidence ruled alternatives out?

Check your understanding

  • Why is reproduction required before fixing — what does it make possible at the end?
  • What does the "no fixes yet, evidence per hypothesis" framing change about agent behavior?
  • Describe the death spiral in Chapter 5 terms, and the four-step escape.
  • What's your lane's superpower in a debugging session?