systematic-debugging

Follow the four-phase process: read the full error and stack trace, reproduce the failure reliably, check recent changes, then form one hypothesis and test it with a minimal change. Never propose a fix before completing root cause investigation.

Trace backward from the error location by asking what called each layer and what values were passed. Add stack trace logging with console.error before the failing operation, then fix at the original trigger point rather than where the symptom appears.

Replace arbitrary setTimeout or sleep calls with condition-based waiting that polls for the actual state you need, such as an event arriving or a count being reached. This eliminates race conditions and typically makes tests faster and deterministic.

Stop and return to root cause investigation with the new information instead of stacking more fixes. If three or more fixes fail, treat it as an architecture problem and question the underlying pattern before attempting further changes.

Never, according to the methodology. Simple bugs still have root causes, emergencies favor systematic investigation over guess-and-check cycles, and apparent quick fixes typically cause rework that costs more time overall.

Use the find-polluter.sh bisection script, which runs each test file individually and checks whether the polluting file or directory appears. It stops at the first test that creates the unwanted state, identifying the culprit directly.