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 arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual state you need, such as waiting for a specific event count. This eliminates race conditions and typically makes tests faster and more reliable.

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 fundamental design problem requiring architectural discussion, not another patch.

Trace backward from the error location by asking what called each function and what values were passed, continuing until you find the original trigger. Add stack trace instrumentation with console.error before the failing operation when manual tracing is insufficient.

Never. Simple bugs have root causes too, and the systematic process is fast for simple issues. Skipping investigation even under time pressure leads to symptom fixes that cause rework and new bugs.

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.