systematic-debugging

Start with root cause investigation: read the full error and stack trace, reproduce the failure consistently, and check recent changes via git diff. Then form one specific hypothesis, test it with the smallest possible change, and only implement a fix after confirming the cause.

Add diagnostic logging at each component boundary, recording what data enters and exits every layer. Run once to gather evidence showing where the chain breaks, then investigate only that failing component instead of guessing across the whole system.

Arbitrary delays create race conditions that pass on fast machines but fail under load or in CI. Replace them with condition-based waiting that polls for the actual expected state, such as an event firing or a value changing, with a timeout and clear error message.

Stop after three failed fix attempts, especially when each fix reveals a new problem in a different place or requires massive refactoring. This pattern indicates an architectural problem, so discuss the design fundamentals before attempting any further patches.

Defense-in-depth adds validation at every layer data passes through: entry point checks, business logic validation, environment guards, and debug instrumentation. This makes the bug structurally impossible rather than relying on a single check that other code paths can bypass.