investigating-bugslisted

# 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:test-driven-development` — Phase 4 captures the bug with a failing test before fixing it. --- ## Phase 1: Root Cause Investigation 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](references/condition-based-waiting.md)); a dependency called a non-deterministic number of times or in a non-deterministic order is another. Read [Diagnosing Flaky Tests](references/diagnosing-flaky-tests.md) for the general diagnostic method and cause catalog. 3. **Check Recent Changes:** Run