systematic-debugging

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

Trace backward through the call chain to find the original trigger 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.

After three or more failed fix attempts, stop and question the architecture. Signals include each fix revealing new problems elsewhere, fixes requiring massive refactoring, or new symptoms appearing after each change. Discuss with your team before attempting more fixes.

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