Debug Code

Essential Principles

Random fixes waste time and create new bugs. Quick patches mask underlying issues; the same bug returns in a different form and the next debug session starts from scratch.

Build a trusted feedback loop before fixing. A fast, deterministic, agent-runnable pass/fail signal makes debugging mechanical. Without one, bisection, instrumentation, and hypothesis testing have nothing reliable to consume.

Find root cause before attempting fixes. You may form provisional hypotheses to build the loop, but do not propose or implement a fix until root cause is confirmed with evidence.

Fix at the correct seam. A regression test is useful only if it exercises the real bug pattern as it occurs at the call site. A shallow test can pass while the original bug remains.

When to Use

Use for any technical issue: test failures, bugs, unexpected behaviour, performance problems, build failures, integration issues. Use especially when under time pressure, when "just one quick fix" seems obvious, after multiple failed fixes, or when you do not fully understand the issue.

Steps