systematic-debugging

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

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 eliminates race conditions and typically runs faster than fixed delays.

Stop and return to root cause investigation with the new information rather than stacking more fixes. If three or more fixes have failed, question the underlying architecture with your team instead of attempting a fourth fix, since repeated failures indicate a structural problem.

Use the find-polluter.sh bisection script, which runs each test file individually and checks whether the unwanted file or directory appears. It stops at the first polluting test and reports the file so you can investigate it directly.

Never, according to this methodology. Simple bugs have root causes too, and systematic investigation is faster than guess-and-check thrashing even during emergencies, since random fixes typically take hours while structured debugging resolves issues in 15-30 minutes.

It means adding validation at every layer data passes through: entry point checks, business logic validation, environment guards, and debug instrumentation. Single-point fixes can be bypassed by other code paths or mocks, while layered validation makes the bug structurally impossible.