systematic-debugging

Follow the four phases: investigate the root cause by reading errors and reproducing consistently, analyze patterns against working examples, form and test a single hypothesis, then implement one fix with a failing test first. Never propose fixes before completing Phase 1.

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual condition you need, such as an event appearing or state changing. The included condition-based-waiting technique fixed 15 flaky tests, raising pass rates from 60% to 100%.

Stop and form a new hypothesis rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss the fundamental design with your team before attempting another fix.

Use the included find-polluter.sh bisection script, which runs test files one by one and stops at the first test that creates the unwanted file or state. Run it with the pollution path and a test file glob pattern.

Never. The skill states that simple bugs have root causes too, and the systematic process is fast for simple issues. Skipping investigation leads to symptom fixes that mask problems and create new bugs.

Trace backward through the call chain from the immediate cause to the original trigger, adding stack trace instrumentation with console.error before the failing operation if needed. Fix at the source, then add defense-in-depth validation at each layer the data passes through.