systematic-debugging

Follow the four phases: read the full error and reproduce the failure consistently, compare against working examples in the same codebase, form one specific hypothesis and test it minimally, then write a failing test before implementing the fix. Never propose a fix before completing root cause investigation.

Trace backward from the error location by asking who called each function and what values were passed, continuing until you find where the invalid data originated. Add stack-trace logging with console.error before the failing operation if manual tracing is not possible.

The skill mandates root cause investigation even during emergencies, arguing that systematic debugging is faster than repeated guess-and-check cycles. Quick symptom fixes typically lead to recurring incidents and more downtime overall.

Replace hardcoded setTimeout or sleep calls with condition-based waiting that polls for the actual state you need, such as an event appearing or a count being reached. This eliminates race conditions and typically makes tests faster and fully reliable.

Stop and question the architecture rather than attempting a fourth fix. Repeated failures where each fix exposes new problems elsewhere indicate a structural issue, so discuss the fundamental design with your team before continuing.

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