Debug Session Workflow

A structured debug session with Claude Code follows a five-step workflow: observe, hypothesize, test, fix, verify. Each step has a specific prompt pattern. Observe: "Read the error output and the relevant source files. Describe what you see." Hypothesize: "Based on the code and the error, what are the three most likely root causes?" Test: "Add logging or write a test that confirms or eliminates each hypothesis." Fix: "Implement the fix for the confirmed root cause." Verify: "Run the test suite and confirm the fix resolves the issue without breaking anything else."

The discipline is in step two — generating multiple hypotheses before testing any of them. Developers (and Claude, if not prompted otherwise) tend to fixate on the first plausible explanation and spend twenty minutes proving it wrong before considering alternatives. Three hypotheses up front costs two minutes of thinking and saves twenty minutes of misdirected investigation.

1. 1. Observe "Read the error and the source files. Describe the symptom and the relevant code." This grounds Claude in the specific context before it starts guessing.
2. 2. Hypothesize "What are the three most likely root causes?" Forces divergent thinking. The correct cause is usually in the top three. If not, the hypotheses at least narrow the search space.
3. 3. Test, Fix, Verify Test each hypothesis with targeted logging or a unit test. Fix the confirmed cause. Run the full test suite to verify no regressions. The test you wrote becomes a permanent regression guard.