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 verified by a failing test. Never propose fixes before completing Phase 1.

Trace backward through the call chain from the immediate cause to the original trigger, asking what called each level and what value was passed. Add stack trace instrumentation with console.error before the failing operation, then fix at the source rather than the symptom.

Stop and return to Phase 1 to re-analyze with new information instead of stacking more fixes. If three or more fixes have failed, question the architecture itself and discuss with your team before attempting another fix.

Replace arbitrary setTimeout or sleep delays 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 timeout, which eliminates race conditions and typically speeds up execution.

Never, according to this methodology. Emergencies, simple-looking bugs, and manager pressure are exactly when systematic investigation matters most, since guess-and-check thrashing is slower than disciplined debugging and symptom fixes create new bugs.

Use the 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.