Bug Investigation and Fix

Structured bug workflow: capture → reproduce → root cause → failing test → fix → verify.

Iron Laws

1. Reproduce before investigating. You cannot fix a bug you cannot trigger reliably.
2. Find root cause before writing any fix. Symptom fixes are failure. Three failed fix attempts means you haven't found the real cause yet.
3. Write a failing test before the fix. The test proves your diagnosis is correct and prevents regression.
4. One hypothesis at a time. Test the most likely cause with the smallest possible change. Never change multiple things simultaneously.
5. Verify with the original repro — not just the unit test. The user-visible symptom must be confirmed resolved.

Phase 1 — Capture

Collect everything needed to understand and reproduce the issue: