process-systematic-debugging

Start by documenting exact reproduction steps, frequency, and environment, then add structured logging at every layer boundary. If the bug remains unreproducible, narrow the scope or gather more context rather than applying speculative fixes.

A systematic protocol follows five phases: reproduce the bug deterministically, isolate the narrowest triggering code path, form 2-3 testable hypotheses, verify the root cause with logging or failing tests, then apply the narrowest safe fix with a regression test.

Use binary search across the stack by adding logging at each layer boundary from client to API to service to database. Identify the last known good state via git history and create a minimal reproduction that strips unrelated code.

Skip the full protocol when the bug is a clear typo with an obvious fix, or when it was already isolated and needs only a one-line change. For general code quality feedback rather than bug diagnosis, use a code review process instead.

This is a Heisenbug where console logging changes timing and masks race conditions. Switch to non-invasive tracing such as database query logs, network timestamps, or external request recording instead of inline console.log statements.

Design a single experiment or test that distinguishes between the hypotheses. If that is impossible, pick the hypothesis with the narrowest fix scope and test it first, documenting why rejected hypotheses were ruled out.