systematic-debugginglisted

# Systematic debugging Random fixes waste time and create new bugs. Before proposing any fix, complete the four phases below in order. ## The rule No fixes without root-cause investigation first. If phase 1 is incomplete, no fix may be proposed. ## Phase 1: investigate 1. Read every line of the error, stack trace, and log output. Note file paths, line numbers, error codes. 2. Reproduce the failure. If it is not consistently reproducible, gather more data before guessing. 3. Check what changed. Run `git diff` and `git log --oneline -10` from the project root to see recent changes. 4. For multi-component systems, add instrumentation at each component boundary and run once to see which layer fails before investigating further. 5. Trace bad values backward to their source. Fix at the origin, not the symptom. ## Phase 2: find the pattern 1. Locate similar working code in the same codebase. Compare it to the broken code line by line. 2. If following a reference implementation, read it completely before adapting. No skimming. 3. List every difference between working and broken, no matter how small. ## Phase 3: hypothesize and test 1. State one hypothesis: "I think X is the root cause because Y". Be specific. 2. Make the smallest possible change to test it. One variable at a time. 3. If the change does not resolve the issue, form a new hypothesis. Do not stack another fix. 4. If you do not understand something, say so. Do not pretend. ## Phase 4: fix 1. Write a failing tes