systematic-debugging

Follow a four-phase process: read error messages and reproduce the issue consistently, compare against working examples, form falsifiable hypotheses tested with discriminator commands, then implement one fix verified by a failing test. Never propose fixes before completing root cause investigation.

Replace setTimeout and sleep calls 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, which eliminated 15 flaky tests and raised pass rates from 60% to 100% in documented sessions.

Use the find-polluter.sh bisection script with the polluted file path and a test pattern. It runs each test file individually and stops at the first one that creates the unwanted file or directory, identifying the exact polluting test.

Stop attempting fixes and question the architecture. Repeated failures where each fix reveals new problems elsewhere indicate a structural issue, not a wrong hypothesis. Discuss refactoring the pattern with your team before attempting another fix.

Single-point validation can be bypassed by different code paths, mocks, or refactoring. Defense-in-depth adds checks at entry points, business logic, environment guards, and debug instrumentation, making the bug structurally impossible rather than merely patched.