Debug systematically

Find the real cause before changing any code.

Steps

1. Reproduce it reliably. Capture the exact inputs, environment, and the smallest case that triggers it.
2. State expected vs. actual behavior precisely.
3. List hypotheses — the most likely causes, ranked.
4. Test the cheapest hypothesis first with a targeted check or log, not a shotgun change.
5. Narrow by bisecting: disable half, see if it persists, repeat.
6. Once found, write a failing test, then fix, then confirm the test goes green.

Output

The root cause, the evidence that confirms it, the minimal fix, and the regression test that locks it in.