systematic-debugging

Follow the four-phase process: investigate the root cause by reading errors and reproducing consistently, compare against working examples, test one minimal hypothesis at a time, then implement a single fix with a failing test. Never propose fixes before completing root cause investigation.

Use the find-polluter.sh bisection script with the polluted path and a test file pattern, for example ./find-polluter.sh '.git' 'src/**/*.test.ts'. It runs each test individually and stops at the first one that creates the pollution.

Replace arbitrary setTimeout or sleep calls with condition-based waiting that polls for the actual condition you need, such as an event appearing or a state changing. Poll every 10ms with a timeout, and only use fixed delays for documented timing behavior.

Stop attempting fixes and question the architecture. Repeated failures where each fix reveals new problems elsewhere indicate a fundamentally wrong pattern, not a failed hypothesis. Discuss refactoring the architecture before trying another fix.

The process applies to any technical issue including simple bugs, since simple issues have root causes too. The only exception is truly environmental or timing-dependent issues, which should be documented and handled with retries, timeouts, and monitoring.