systematic-debugging

Start by reading the full error message and stack trace, then reproduce the failure consistently. Check recent changes, gather evidence at each component boundary, form one hypothesis, and test it with the smallest possible change before implementing a fix.

Replace arbitrary setTimeout or sleep delays with condition-based waiting that polls for the actual expected state, such as an event appearing or a count being reached. Poll every 10ms with a clear timeout error message.

Root cause tracing follows a bug backward through the call stack from where the error appears to where the bad value originated. You fix the source rather than the symptom, then add validation at each layer the data passes through.

After three or more failed fix attempts, stop and question the architecture. Signals include each fix revealing new problems elsewhere, fixes requiring massive refactoring, or fixes creating new symptoms in different places.

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