systematic-debugging

Follow the four-phase process: read error messages and reproduce the issue, compare against working examples, form a single hypothesis and test it minimally, then implement one fix with a failing test. Never propose fixes before completing the investigation phase.

Replace setTimeout and sleep calls with condition-based waiting that polls for the actual expected state, such as an event appearing or a count being reached. The included TypeScript helpers waitForEvent, waitForEventCount, and waitForEventMatch poll every 10ms with a configurable timeout.

Stop after three failed fixes and question the architecture rather than attempting a fourth. Repeated failures where each fix reveals new problems elsewhere indicate a structural issue that requires redesign discussion, not another patch.

Use the included find-polluter.sh bisection script with the polluted path and a test file pattern. It runs each test individually and stops at the first one that creates the unwanted file or directory.

The Skill states it is never acceptable to skip the process, even for simple bugs or emergencies. Simple issues still have root causes, and systematic investigation is faster than guess-and-check thrashing under time pressure.