Debug

Debug

The Rule

No fixes without root cause investigation. If you can't explain WHY it's broken, you can't fix it. You're just guessing.

The Loop

Phase 1: Investigate

• Collect symptoms: what fails, when, error messages, stack traces
• Read the relevant code (not just the error line, the surrounding context)
• Check git log for recent changes in affected files
• Reproduce the issue. If you can't reproduce it, you can't verify a fix.

Phase 2: Pattern match

Does this look familiar?

Pattern	Typical signal
Race condition	Intermittent, timing-dependent, works in debug mode
Nil/null propagation	Crashes on missing data, works with full records
State corruption	Works first time, breaks on retry or concurrent use
Integration failure	Works locally, breaks with external service
Config drift	Works in one environment, not another
Stale cache	Works after restart, breaks after time passes
Off-by-one	Works for most inputs, fails at boundaries
Import/dependency	Works in isolation, breaks when composed

Phase 3: Hypothesize and test

1. Form a hypothesis: "I think X is happening because Y"
2. Design a test: add targeted logging, write a minimal reproduction, or add an assertion
3. Run it. Does the evidence support the hypothesis?

3-strike rule: If 3 hypotheses fail, STOP. You're probably wrong about the problem space. Step back and:

• Re-read the code from scratch
• Check your assumptions (is the data what you think it is?)
• Widen the scope (is the bug actually in the file you're looking at?)
• Ask for help

Phase 4: Fix with minimum force

• Fix the root cause only. Smallest diff possible.
• Write a regression test that fails without the fix
• Don't fix adjacent issues in the same change

Phase 5: Verify

• Reproduce the original issue. Confirm it's gone.
• Run the full test suite
• Confirm the regression test passes

Escalation

If you've been through the loop 3+ times across multiple attempts and the bug persists, this isn't a bug. It's an architecture problem. Stop fixing symptoms and start asking: is the design wrong?

Output Format

When reporting a fix:

Symptom:    [what was observed]
Root cause: [why it happened]
Fix:        [what changed]
Evidence:   [how we confirmed]
Regression: [test that prevents recurrence]

Rationalization Prevention

Thought	Reality
"I think I know what this is, let me just fix it"	You thought you knew last time too. Investigate first.
"It's probably just a typo"	Confirm it's a typo before "fixing" it.
"Let me try a few things"	That's shotgun debugging. Form a hypothesis first.
"This worked before, something must have changed"	Great. git log will show you what changed. Start there.