Systematic Debugging

Use when facing a bug, failing test, regression, or unexpected behavior.

Iron Rule

Do not propose fixes until you have a root-cause hypothesis backed by evidence.

4 Phases

1) Investigate

• Reproduce reliably.
• Read full error output and stack traces.
• Check recent changes (git log, git diff).
• Add targeted instrumentation at boundaries (inputs/outputs).

2) Compare

• Find nearby working examples in this repo.
• Compare broken vs working behavior line-by-line.
• List concrete differences.

3) Hypothesize

• State one hypothesis clearly.
• Run one minimal test/change to validate it.
• If wrong, discard and form a new hypothesis.

4) Fix + Verify

• Write/keep a failing reproduction test first.
• Implement the smallest root-cause fix.
• Re-run target test + relevant suite.
• Confirm no regressions.

Rules

• One fix at a time.
• No shotgun edits.
• No “probably fixed.”
• If two attempts fail, return to Phase 1 and gather more evidence.

Completion Criteria

You can explain:

1. what broke,
2. why it broke,
3. what changed to fix root cause,
4. which commands now pass.