systematic-debugging

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

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, which eliminates race conditions and typically speeds up test execution.

Stop after three failed fixes and question the architecture rather than attempting a fourth fix. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, so discuss architectural refactoring before continuing.

Use the find-polluter.sh bisection script, which runs each test file individually and checks whether the unwanted file or directory appears. It stops at the first polluting test and reports the file so you can investigate it directly.

Never. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation leads to symptom fixes that cause recurring failures and rework, which is slower than systematic debugging.