systematic-debugging

Follow the four phases: investigate the root cause by reading errors and reproducing the issue, analyze patterns by comparing working code, form and test a single hypothesis, then implement one fix verified by a failing test. Never propose fixes before completing the investigation phase.

Trace backward through the call chain from the error point to the original trigger, asking what called each function and what value was passed. Add stack trace instrumentation with console.error before the failing operation if manual tracing is not possible.

The skill mandates root cause investigation even under time pressure, arguing systematic debugging is faster than guess-and-check thrashing. Quick symptom fixes set bad patterns and typically cause rework and new bugs.

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual expected condition, such as an event appearing or state changing. The included condition-based-waiting technique raised pass rates from 60% to 100% in a real session.

Stop attempting more fixes and question the architecture instead. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, which should be discussed before further fix attempts.

Use the included find-polluter.sh bisection script, which runs test files one by one and checks whether the unwanted file or directory appears after each run. It stops and reports the first test that creates the pollution.