systematic-debugging

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

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

Stop after three failed fixes and question the architecture rather than attempting a fourth. Repeated failures where each fix reveals new problems elsewhere indicate a structural issue that requires architectural discussion, not another symptom patch.

Use the find-polluter.sh bisection script with the polluted path and a test file pattern. It runs each test individually and stops at the first one that creates the unwanted file or directory, identifying the exact polluting test.

Add defense-in-depth validation after fixing a bug caused by invalid data. Validate at the entry point, business logic, environment guards, and debug instrumentation layers so the bug becomes structurally impossible even if one check is bypassed.