systematic-debugging

Follow the four-phase process: read the full error and reproduce reliably, compare against a working example of the same pattern, form one hypothesis and test the smallest change, then implement with a failing test first. Never stack multiple fixes on an unconfirmed hypothesis.

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

Stop after 3 or more failed fix attempts on the same bug, especially when each fix reveals new shared state in a different place or requires massive refactoring. That pattern indicates a wrong architecture, not a failed hypothesis, so discuss with the team before attempting more fixes.

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 state, identifying the exact polluting test.

Defense-in-depth adds validation at every layer data passes through: entry point, business logic, environment guards, and debug instrumentation. Apply it after finding a root cause caused by invalid data, since a single check can be bypassed by other code paths, refactoring, or mocks.