systematic-debugging

Follow the four-phase process: read error messages fully, reproduce the issue consistently, check recent changes, and gather evidence at each component boundary. Then form a single hypothesis, test it minimally, and only implement a fix after the root cause is confirmed.

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.

Trace backward through the call chain to find where the bad value originated rather than fixing where the error appears. Add stack trace instrumentation with console.error before the failing operation, then fix at the source and add validation at each layer.

Stop after three failed fix attempts. If each fix reveals a new problem in a different place or requires massive refactoring, the pattern itself is likely wrong. Discuss the architecture with your team before attempting a fourth fix.

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