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 verified fix. Never propose fixes before completing the investigation phase.

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

Stop and return to root cause investigation with the new information rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss the fundamental design before attempting another fix.

Trace backward from the immediate cause by asking what called each function and what values were passed, until you find the original trigger. Add stack trace instrumentation with console.error before the failing operation if manual tracing is not possible.

Never, according to this methodology. Even under time pressure or for seemingly simple bugs, skipping investigation leads to symptom fixes that mask root causes and create new bugs. Systematic debugging is faster than guess-and-check thrashing.

Use the included find-polluter.sh bisection script, which runs test files one by one and checks whether the unwanted file or directory appears after each run. It stops at the first polluting test and reports it for investigation.