systematic-debugging

Follow the four phases: first investigate the root cause by reading errors fully and reproducing consistently, then compare against working examples, form one hypothesis and test it minimally, and finally implement a single fix verified by a failing test. Never propose fixes before completing root cause investigation.

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 clear timeout error, and only use arbitrary delays when testing actual timing behavior with a documented reason.

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, fix at the source, then add validation at each layer the data passes through.

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 find-polluter.sh bisection script with the file to check and a test pattern, such as ./find-polluter.sh '.git' 'src/**/*.test.ts'. It runs each test individually and stops at the first one that creates the unwanted file or directory.

No. The skill explicitly states simple bugs have root causes too and systematic investigation is faster than guess-and-check thrashing even under time pressure. Skipping the process is treated as a red flag regardless of urgency.