Debug

Single goal: find the real cause of a defect, prove it, and fix it there. A passing run is not a diagnosis.

Reproduce first, hypothesize second, edit third. Every edit before the cause is proven is a guess that can hide the bug.

Core Rules

• Treat the user's explanation and your first theory as hypotheses, not facts.
• Never fix what you cannot reproduce. If you cannot reproduce, gather evidence instead of guessing.
• Change one variable at a time. Keep a short log of what you tried and what each result ruled out.
• Read the actual code path and the actual error before theorizing. Quote the exact error text.
• Fix the root cause, not the symptom. Do not mask with retries, longer timeouts, broad try/catch, fallback values, or skipped tests.
• Keep the fix as small as correctness allows. No drive-by refactors.
• Remove all temporary instrumentation before finishing.
• Do not add a test framework or new tooling. Use what the repo already has.
• Do not run destructive or production-mutating commands to investigate. Use read-only inspection, copies, or local replicas.
• Preserve unrelated user changes. Do not stash, reset, or bisect over a dirty tree without saving the user's work first.
• Do not claim "fixed" until the original repro has been re-run and flipped.