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 and 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, which eliminated flakiness and ran 40% faster in real sessions.

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 changes before continuing.

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.

Never. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation under time pressure leads to guess-and-check thrashing that is slower than systematic debugging.