systematic-debugging

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

Use root cause tracing: observe the symptom, find the immediate cause, then trace backward through each caller asking what value was passed until you find the original trigger. Add stack trace instrumentation with console.error before the failing operation when manual tracing is not possible.

Replace arbitrary timeouts with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. Poll every 10ms with a clear timeout error, and only use fixed delays when testing actual timing behavior with documented justification.

Stop and return to Phase 1 to re-analyze with 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 with your team before attempting further changes.

Never, according to the skill's iron law: no fixes without root cause investigation first. Even under emergency time pressure, systematic debugging is faster than guess-and-check thrashing, and symptom fixes are classified as failure.

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 at the first polluting test and reports the file for investigation.