Systematic Debugging

Systematic Debugging

Core Principle

Random fixes waste time and create new bugs. Always find the root cause before attempting fixes.

Phase 1 — Reproduce

Before anything else, reproduce the failure:

# Run the failing test or trigger the bug
cargo test <failing_test_name>

Record: exact error message, stack trace, which input triggers it.

Phase 2 — Isolate

Narrow the scope:

• Is it a single function, a module boundary, or a data flow issue?
• Add dbg!() or eprintln!() at suspected boundaries.
• Check: does the bug appear in the most recent commit? Use git bisect if needed.

Phase 3 — Understand

Before writing any fix:

• State the root cause in one sentence.
• Explain why the current code produces the wrong behavior.
• Predict what a correct fix would change.

If you cannot do all three, you have not finished Phase 3.

Phase 4 — Fix and Verify

• Write a test that captures the root cause (this test should fail before the fix).
• Apply the minimal fix.
• Run the full test suite to check for regressions.

When NOT to Use

• Typos and trivial syntax errors. Just fix them.
• Build configuration issues. Check Cargo.toml first.