systematic-debugging

Follow the four phases: read error messages and reproduce the issue consistently, compare against working examples, form one hypothesis and test it minimally, then implement a single fix verified by a failing test. Never propose fixes before completing root cause investigation.

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 if manual tracing is not possible.

Stop and return to Phase 1 to re-analyze with the new information rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss the fundamental design before attempting another fix.

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual state you need, such as an event appearing or a count being reached. Poll every 10ms with a clear timeout error message.

The skill states it is never acceptable, including for simple bugs, emergencies, or manager pressure. Systematic investigation is faster than guess-and-check thrashing, and simple bugs have root causes too.

Use the included find-polluter.sh bisection script, which runs each test file individually and checks whether the unwanted file or directory appears, stopping at the first test that creates the pollution.