debug

Debugging Discipline

The Iron Law

NO FIXES WITHOUT UNDERSTANDING THE ROOT CAUSE FIRST.

Not "try this and see." Not "it might be X." You trace it, you understand it, then you fix it. Violating the letter of this rule is violating the spirit.

When to Use

• Any error, exception, or stack trace
• Unexpected behavior (wrong output, missing data, UI not updating)
• Performance degradation (slow endpoint, high memory, timeout)
• Flaky behavior (works sometimes, fails sometimes)
• Something that "should work" but doesn't

The Process

Four phases. Sequential. No skipping.

REPRODUCE → INVESTIGATE → FIX → VERIFY

Phase 1: REPRODUCE

Confirm the bug exists. Get a reliable way to trigger it.

• Run the failing code / hit the failing endpoint / reproduce the user's steps
• Capture the exact error output, status code, or wrong behavior
• Note the environment: which service, which endpoint, what input
• If you cannot reproduce it, you cannot fix it — investigate why reproduction fails first

Gate: You have a repeatable reproduction before moving to Phase 2.

Phase 2: INVESTIGATE

Understand what is happening and why. This is where the real work lives.

• Read the full stack trace — not just the error message, the entire call chain
• Trace the data flow from input to failure point
• Find where expectations diverge from reality (expected X, got Y)
• Check recent changes: git log --oneline -10 -- <file> on the failing path
• Use the debug agents as operational tools:

Symptom	Agent
Stack trace / exception	/debug error
Slow response / timeout	/debug performance
4xx/5xx / CORS / auth issues	/debug api
Recurring patterns in logs	/debug logs

Gate: You can explain the root cause in one sentence before moving to Phase 3.

Phase 3: FIX

Minimal, targeted change. One fix per root cause.

• Fix the root cause, not the symptom
• Change only what is necessary — no drive-by refactoring
• If the fix requires changing more than 3 files, pause and verify you're fixing the right thing
• If the fix is a try/except or error suppression, you are not fixing — you are hiding

Phase 4: VERIFY

Confirm the fix works. Confirm nothing else broke.

• Re-run the exact reproduction from Phase 1 — it must pass
• Run related tests: pytest <test_file> or the relevant test suite
• If the bug was in an API: hit the endpoint again, check the response
• If the bug was visual: reload the page, verify the UI
• If you cannot verify, the fix is not complete

Gate: Fresh evidence that the fix works before claiming completion.

Red Flags — STOP and Return to Phase 1

If any of these are true, you have left the process:

• Each fix reveals a new problem in a different place
• You are changing code you don't fully understand
• You are adding try/except or error suppression instead of fixing the cause
• The fix works but you cannot explain why
• You have applied 3+ attempted fixes without success
• You are editing files not in the stack trace

ALL of these mean: STOP. Go back to Phase 2. Re-investigate.

Common Rationalizations

Excuse	Reality
"Let me just try changing this"	That's guessing, not debugging
"It works now, ship it"	If you can't explain why, it's not fixed
"I'll investigate properly next time"	This IS next time
"The error message is misleading"	Read the stack trace, not just the message
"It's probably a library bug"	It's almost never a library bug
"This is too complex to trace"	Break it into smaller steps. Trace each one
"I'll add logging and try again"	Add logging AND read existing logs first

Quick Reference

Phase 1: REPRODUCE  → Can you trigger it reliably?
Phase 2: INVESTIGATE → Can you explain the root cause in one sentence?
Phase 3: FIX        → Minimal change, root cause only
Phase 4: VERIFY     → Fresh evidence it works, no regressions

Impact

From debugging sessions following this discipline:

• Systematic approach: 15-30 minutes to resolution
• Guessing approach: 2-3 hours of thrashing
• First-time fix rate with discipline: ~90%
• First-time fix rate without: ~40%
• Regressions introduced: near zero vs. common