Systematic debugging

Skill 06: Systematic Debugging & Iteration

Purpose: Find and fix the real cause of a failure through evidence, not guessing. Use when: Anything doesn't work as expected, a crash, a wrong result, a flaky behavior, a surprising output. Don't use when: Nothing is actually broken. Don't "debug" working code out of anxiety; that's just risk with no upside.

---

Why this matters

Debugging is where weak reasoners waste the most time, because the instinct under pressure is to guess and thrash: change something plausible, re-run, change something else, re-run, until either it accidentally works (leaving a mystery) or the code is a superstitious mess of unnecessary changes. Systematic debugging replaces guessing with a short, reliable loop built on evidence. It is slower for the first thirty seconds and far faster overall.

The core principle

A bug is a gap between what you believe and what is true. Debugging is finding that gap with evidence: not patching symptoms. You cannot fix what you cannot reliably reproduce and locate. Every step is about narrowing "where the truth differs from my belief" until only one explanation remains.

Fix the root cause, not the symptom. A stack trace or error message names where it surfaced, not why. Patching the surface leaves every sibling path still broken and often hides the real defect.

---

The debugging loop

Step 1: Reproduce it reliably

You cannot fix what you cannot reproduce. Find the smallest, most consistent way to make the bug happen on demand. If it's intermittent, work to make it deterministic (fix the inputs, the timing, the environment). A bug you can trigger at will is already half-solved; a bug you can't reproduce, you can't verify you fixed.

Step 2: Read the actual error

Read the entire error message and stack trace, slowly, start to end. Beginners skim it; the answer is often sitting in it. Note the exact failure, the exact line, the exact values. Don't theorize before you've read the evidence in front of you.

Step 3: Form a specific hypothesis

State a testable belief about the cause: "I think total is wrong because the CSV has a header row that's being summed as data." A hypothesis names a cause and predicts what you'd observe if it were true. "Something's wrong with the parsing" is not a hypothesis, it's a shrug.

Step 4: Test the hypothesis with one change

Make one change or add one observation (a print/log of the suspect value, an assertion, a breakpoint) that will confirm or kill the hypothesis. Predict the result first: "if I'm right, the first summed value will be the header string." Then run and compare to the prediction.

Step 5: Narrow down

• If the hypothesis was confirmed → you've found the cause; go to Step 6.
• If it was wrong → that's progress: you've eliminated a possibility. Use what you observed to form the next hypothesis. Don't discard the observation.

Bisect when lost: cut the problem space in half. Does the value look right halfway through the pipeline? That tells you which half the bug is in. Repeat. Binary search finds a needle in a huge haystack in a few steps.

Step 6: Fix the root cause

Fix the actual cause, at the place where all affected paths route through, not a bandage on the one path that reported the symptom. Ask: why did this happen, and where else could the same cause bite? One guard in the shared function beats a guard in every caller.

Step 7: Verify the fix

Reproduce the original failing case → it now passes. Then check you didn't break anything else (run the surrounding checks/tests). A fix you didn't verify is a guess. A fix that breaks two other things is not a fix.

Step 8: Prevent recurrence

Leave a check (a test/assertion) that would catch this bug if it ever returns. Consider whether the same class of bug exists elsewhere. This is how debugging improves the system instead of just restoring it.

---

When you're truly stuck

Technique	How
Explain it out loud	Describe the problem step by step to a person, a rubber duck, or in writing. The gap often reveals itself as you narrate.
Check your assumptions	List what you're sure is true, then verify each one is actually true. The bug hides in the assumption you didn't check.
Reduce to a minimal case	Strip the problem down until only the bug remains. Removing things until it works localizes the cause.
Read it as if it's someone else's	Re-read the code literally, doing exactly what it says, not what you meant.
Compare working vs broken	If it worked before, what changed? Diff it. Bisect the history.
Step away	After prolonged thrashing, a short break resets a fixated mind faster than more thrashing.

---

Worked example

Symptom: The cost report shows a total that's about $0.42 too high on every run.

Guess-and-thrash (bad): Randomly add rounding, change float to Decimal, tweak the sum order, add abs(). Something eventually shifts the number; you don't know why; the "fix" is fragile.

Systematic (good):

1. Reproduce: Consistent, same overage every run on the sample file. Good.
2. Read evidence: No error; the number is just wrong. Print the list being summed.
3. Hypothesis: The header row ("cost") or a footer/total row is being included as a number.
4. Test: Print each value with its row index. → The last row is a "TOTAL" line the export appends, value $0.42… wait, it's actually a blank-looking row parsed as 0.42? Print reveals the real culprit.
5. Narrow: Confirmed the final row is a summary row, not a data row.
6. Fix root cause: Filter summary rows where they're parsed, so every consumer of the parsed data is correct, not just this report.
7. Verify: Total now matches the hand calculation; other outputs still correct.
8. Prevent: Add a check: "parsed rows never include a row whose label is 'TOTAL'."

The systematic path took five minutes and produced understanding; the thrash could take an hour and produces superstition.

---

Common failure modes

Failure	Fix
Guessing and thrashing	One hypothesis, one test, at a time.
Skimming the error	Read the whole message/trace before theorizing.
Patching the symptom	Trace to root cause; fix where all paths converge.
Changing many things at once	Change one thing; know which change did what.
"It works now" with no idea why	Keep going until you understand it; mystery fixes reappear.
Not verifying the fix	Reproduce the original case; run surrounding checks.
Deleting print/logs and the test	Leave a regression check behind.

Red flags: stop and restart the loop

• You're making changes without a specific hypothesis.
• You haven't actually reproduced the bug.
• You didn't read the full error.
• You're patching the place it crashed rather than the place it went wrong.
• It "works now" and you can't explain what fixed it.
• You've changed five things and the state is more confusing than when you started.

Definition of done for this skill

• The bug was reproduced reliably before fixing.
• The cause was found by evidence, not guessed.
• The fix addresses the root cause where all affected paths converge.
• The original case now passes and nothing else broke.
• A regression check is left behind.

See also

• first-principles-reasoning, hypotheses and assumption-checking.
• self-verification, verifying fixes properly.
• robustness-and-failure-modes, preventing whole classes of bugs.
• context-and-knowledge-management, tracking findings while debugging.