systematic-debugging

Follow the four-phase process: first investigate the root cause by reading errors and reproducing the issue, then analyze patterns against working code, form and test a single hypothesis, and only then implement a verified fix. Never propose fixes before completing root cause investigation.

Use the find-polluter.sh script, which runs each test file sequentially and checks whether a specified pollution path appears after each run. Run it in an isolated checkout with your test runner, and it stops at the first polluting test file.

Replace setTimeout or sleep calls with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. Poll every 10ms with a clear timeout error, and only use arbitrary delays when testing actual timing behavior.

After three failed fixes, stop and question the architecture rather than attempting a fourth fix. Repeated failures where each fix reveals new problems elsewhere indicate a structural issue that requires architectural discussion, not more patches.

Add defense-in-depth validation whenever a bug was caused by invalid data flowing through multiple components. Validate at the entry point, business logic, environment guards, and debug instrumentation layers, since single checks can be bypassed by other code paths, refactoring, or mocks.