systematic-debugging

Follow the four-phase process: first investigate the root cause by reading errors and reproducing the issue, then analyze patterns against working code, form a single testable hypothesis, and implement one verified fix. Never propose fixes before completing the investigation phase.

Use the included find-polluter.js script, which runs test files one by one and checks whether a polluting artifact like a .git directory appears after each run. It stops at the first test that creates the pollution and reports the culprit file.

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 condition-based-waiting reference includes a generic waitFor implementation and domain-specific helpers.

Stop after three failed fixes and question the architecture rather than attempting a fourth fix. Repeated failures where each fix reveals new problems elsewhere indicate a structural issue that requires discussing a redesign with your team.

The process applies to any technical issue, including seemingly simple bugs, since simple issues have root causes too. The only exception is when investigation proves the issue is genuinely environmental or external, in which case you document findings and add appropriate handling.