systematic-debugging

<objective>
Find the root cause before writing fixes. Understanding why something breaks leads to correct fixes. Guessing wastes time and creates new problems.

Core principle: If you can't explain WHY it's broken, you're not ready to fix it. Every
fix must address a specific, understood root cause. </objective>

<when-to-use>
Use for any technical issue: test failures, build errors, bugs, unexpected behavior, performance problems. Especially valuable when previous attempts haven't worked or when tempted to try a "quick fix."
</when-to-use>

<start-with-evidence>
Read error messages completely. Stack traces, line numbers, and error codes contain valuable information. The error message often points directly to the problem.

Work to reproduce the issue reliably. If you can't trigger it consistently, gather more
data before proposing solutions. Document the exact steps that trigger the failure.

Check what changed recently. Review commits, new dependencies, configuration changes,
environmental differences. Most bugs correlate with recent changes.
</start-with-evidence>

<trace-the-problem>
Follow the data flow backward from the error. Where does the bad value originate? Work through the call stack until you find the source. Understanding the complete path from source to symptom reveals the true problem.

When multiple components interact, add diagnostic output at each boundary to identify
which component fails. This narrows the investigation to the specific failing layer.
</trace-the-problem>

<compare-with-working-code>
Find similar code that works correctly. Compare the working and broken versions systematically. Every difference matters until proven otherwise.

When implementing a pattern, read reference implementations thoroughly. Understand their
dependencies, settings, and environmental requirements. </compare-with-working-code>

<test-understanding>
Form a clear hypothesis: "X causes the problem because Y." Test with the smallest possible change. Change one vari