Debugging And Root Cause — Claude Code Guide

Diagnosis separates symptom, cause, and fix

A bugfix becomes safer when the symptom is reproduced, competing hypotheses are tested, and the smallest causal change is identified. A plausible patch is not root-cause evidence.

Keep diagnosis artifacts short and tied to observable behavior.

Diagnosis sequence

1. Record the exact symptom and context.
2. Build a minimal reproduction.
3. Trace the relevant code path and data.
4. List competing hypotheses.
5. Run a targeted check for the leading cause.
6. Only then propose the smallest fix.

Diagnosis record

{"symptom":"<observed failure>","reproduction":"<steps>","evidence":["<path:line>"],"hypothesis":"<cause>","check":"<test or command>","status":"documented example"}