root-cause-debugging

# Root-Cause Debugging ## Overview Random fixes waste time and create new bugs. Quick patches mask underlying issues. **Core principle:** ALWAYS find the root cause before attempting fixes. Symptom fixes are failure. ## The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` Use this for ANY technical issue: a task returned to need_revision, a failing test, a red pipeline, unexpected behavior. Use it ESPECIALLY under time pressure — systematic is faster than guess-and-check thrashing. ## The Four Phases Complete each phase before the next. ### Phase 1 — Root cause investigation 1. **Read the feedback completely**: the reviewer/QA/pipeline comment on the task, the full error output, stack traces, exact files/lines/messages. They often contain the exact answer. 2. **Reproduce consistently** in the task workspace: exact steps, does it happen every time? Not reproducible → gather more data, don't guess. 3. **Check recent changes**: git diff, recent commits on the task branch, config changes. 4. **Multi-component systems** (API → service → database): add diagnostic logging at each component boundary — what enters, what exits — run once, and locate WHICH layer breaks before touching anything. 5. **Trace the bad value backward** from where the error appears to where it originates. Fix at the source, not at the symptom. ### Phase 2 — Pattern analysis - Find working examples of the same pattern in the codebase (codebase_search, grep_code). - Read the reference i...