systematic-debugging

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

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, and only use fixed delays when testing documented timing behavior.

After three or more failed fixes, stop and question the architecture rather than attempting another fix. Repeated failures where each fix reveals new problems elsewhere indicate a design problem, not a wrong hypothesis, and require architectural discussion.

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

Add defense-in-depth validation after fixing a bug caused by invalid data, placing checks at the entry point, business logic, environment guards, and debug instrumentation. Single-point validation can be bypassed by other code paths, mocks, or refactoring.