investigating-bugs

Investigating bugs

Avoid "guess-and-check" coding. Always identify the root cause before making changes.

THE IRON LAW: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Violating the letter of the rules is violating the spirit of the rules.

REQUIRED PREREQUISITE: You must have already completed slow-powers:working-in-isolation — debug from an isolated workspace.

REQUIRED BACKGROUND: You must understand slow-powers:working-with-tdd — Phase 4 captures the bug with a failing test before fixing it.

---

Phase 1: root cause investigation

Complete these steps before changing any code:

1. Read error messages and stack traces: Read every line of the error. Note the exact file, line number, and error codes.
2. Reproduce consistently: Identify the exact steps, inputs, or environment needed to trigger the bug. If it cannot be reproduced, gather more logs instead of guessing.
   • For flaky tests (pass sometimes, fail under load or only in CI), find the non-determinism before changing anything — don't rerun until it goes green. Arbitrary sleep/timeout delays are one common cause (wait on the actual condition, not a guessed duration — see condition-based waiting); a dependency called a non-deterministic number of times or in a non-deterministic order is another. Read diagnosing flaky tests for the general diagnostic method and cause catalog.
3. Check recent changes: Run git diff. Analyze recent commits, dependency additions, or configuration changes.
4. Gather evidence in multi-component systems:
   • Log inputs and outputs at every component boundary.
   • Instrument the layers step by step (for example, workflow → build script → runtime → database) to pinpoint exactly where the state breaks.
5. Trace data flow: Trace variables backward from the failure point to their source. Fix the bug at the source, not the symptom.
   • When manual tracing dead-ends, instrument the suspect operation: log the key inputs, relevant environment, and a captured stack trace (new Error().stack) just before it runs. In tests, write to stderr — a logger may be suppressed. Read the captured stack to find the original caller, then remove the instrumentation.