Debug

Systematic Debugging

Quick Reference

The Loop

1. Reproduce -- make the failure happen on demand
2. Read -- the actual error, the actual stack, the actual input
3. Narrow -- bisect until the failure is in a small known region
4. Hypothesize -- one falsifiable statement about the cause
5. Test the hypothesis -- instrument or probe, do not fix yet
6. Fix -- the cause, not the symptom
7. Confirm -- same reproduction steps now pass
8. Regression-test -- a test that would have caught this

Steps 1-5 are the work. Skipping to 6 is why bugs get "fixed" twice.

Reproduce Before You Theorize

A bug you cannot trigger on demand is a bug you cannot confirm you fixed.

• Write down the exact steps, input, and environment that trigger it
• Reduce to the smallest reproduction that still fails (fewer files, less data, fewer steps)
• If it only fails in CI or production, find the difference: version, env var, data volume, timezone, concurrency, file system, locale
• If it is intermittent, run it in a loop and record what differs between pass and fail

No reproduction means no verification later. Say so instead of guessing.

Read the Actual Error

Pattern-matching an error to a familiar shape is the most common wrong turn.

• Read the full message, not the first line -- the cause is often in a nested or wrapped error
• Read the stack from the top frame in your own code, not the framework frames above it
• Check the line number against the file you are actually running (stale build, wrong virtualenv, cached bundle)
• Distinguish the error that surfaced from the error that caused it -- "connection refused" is a symptom, not a cause
• If the message contradicts the code, suspect what you are running, not what you are reading

Narrow by Bisection

Halve the search space instead of scanning it.

Ten halvings cover a thousand candidates. Reading a thousand lines does not.

One Hypothesis at a Time

State the cause as a sentence that can be proven wrong, then try to prove it wrong.

Weak:   "something is wrong with the cache"
Strong: "the cache key omits the tenant id, so tenant B reads tenant A's row"
        Disproof: log the computed key for two tenants -- if they differ, wrong.

• One hypothesis per experiment, or you cannot tell which change mattered
• Change one variable at a time and re-run between changes
• Predict the result before you run it -- a surprise means your model is wrong, which is information
• Write the hypothesis down for anything that takes more than a few minutes

Instrument, Don't Guess

When you do not know a value, measure it.

• Log or print the actual values at the boundary you suspect -- types, not just values
• Use a debugger or breakpoint when state is complex; use logs when timing or ordering matters
• Assert your assumptions inline so a wrong one fails loudly instead of flowing downstream
• For performance bugs, profile before optimizing -- the slow part is rarely where it feels
• For concurrency bugs, log with timestamps and thread/task ids, or the ordering stays invisible
• Remove the instrumentation before you ship, or promote it to real logging on purpose

Fix the Cause, Not the Symptom

Symptom fixes are sometimes the right call under pressure. When you take one, say it is a mitigation and leave the real cause written down.

The Stop Rule

After two failed fix attempts, stop editing code.

1. State what you believed the cause was
2. State what you changed and what actually happened
3. List the assumptions you have not verified
4. Ask for the missing information, or start over from reproduction

A third guess after two wrong ones is not debugging, it is shotgunning. The cost of shotgunning is a diff nobody can review and a bug that comes back.

After the Fix

• Confirm with the original reproduction steps, not a variant of them
• Write the regression test -- the one that fails before the fix and passes after
• Check for the same mistake elsewhere in the codebase (same wrong pattern, other call sites)
• Note the root cause in the commit body, not just the change

Anti-Patterns