Debugging Techniques: Systematic Troubleshooting with Claude Code#

Phase 1: UNDERSTAND THE SYMPTOM
  What is happening? What should be happening?
       │
Phase 2: REPRODUCE
  Can you make it happen reliably?
       │
Phase 3: INVESTIGATE ROOT CAUSE
  Why is it happening? Where does the problem originate?
       │
Phase 4: FIX AND VERIFY
  Fix the root cause, verify with tests.

Vague (Claude has to guess):
  "the login is broken"

Precise (Claude knows what to investigate):
  "login returns 401 after session timeout. the token
   refresh endpoint returns 200 but the new token isn't
   being stored in the cookie. here's the network trace:
   [paste]"

"the test fails with 'expected 200 but got 401'.
 reproduce it by running: go test ./internal/auth/..."

"users report that checkout fails intermittently.
 write a test that simulates concurrent checkout
 requests to reproduce the race condition"

"this only fails in CI. here's the CI log output:
 [paste]. the local environment uses Go 1.22 but
 CI uses Go 1.21. check if any 1.22 features are
 being used"

Symptom:    401 response on login
    ↑
Immediate:  token validation fails
    ↑
Deeper:     token has wrong expiry timestamp
    ↑
Root cause: clock skew between auth service and token issuer

"the error is in auth.go:47 where validateToken()
 returns false. trace backward to find where the
 token gets its expiry timestamp and why it might
 be wrong"

"fix the clock skew issue by using the token
 issuer's timestamp instead of the local clock.
 write a test that reproduces the original bug
 (wrong expiry), then verify it passes with the fix"

Bad:  "the test still fails, try something else"
      (Claude doesn't know what error to address)

Good: "the test fails with: 'panic: runtime error:
       invalid memory address or nil pointer
       dereference' at auth.go:47"
      (Claude knows exactly what's wrong and where)

Bad:  "it's broken again"
      (no information to work with)

Good: "same nil pointer, but now at auth.go:52.
       looks like the fix moved the problem
       downstream -- user.Token is nil when the
       account has never logged in before"
      (Claude understands the fix was incomplete)

"the panic is at handler.go:89 where it calls
 user.GetProfile(). trace backward to find how
 'user' gets its value -- it might be nil when
 the session lookup fails silently"

"trace the request token from the HTTP header
 through the middleware chain to the handler.
 find where validation happens and what happens
 when validation fails"

"this worked last week. look through the git log
 for changes to the auth module since Monday"

"use git bisect to find which commit broke the
 login test. the test is:
 go test -run TestLoginWithExpiredToken ./internal/auth/"

"git blame auth.go around line 47. who changed
 this last and what was the commit message?"

"here's the error log from production: [paste].
 identify the pattern -- what requests trigger
 this error? is there a common thread (same user,
 same endpoint, same time of day)?"

cat error.log | claude -p "analyze these errors.
group by root cause and rank by frequency"

"think through what happens if two users trigger
 checkout simultaneously. where could the race
 condition occur in our current checkout flow?"

"what could cause pagination to silently drop
 results? consider the database query, the
 cursor handling, and the response serialization"

Step 1: Read the full error output
  "run go test ./internal/auth/ -v and show me
   the complete output"

Step 2: Identify which assertion failed
  "the test expects 200 but gets 401. what's the
   auth middleware doing to this test request?"

Step 3: Trace the unexpected value
  "the token is being rejected. check what token
   the test fixture provides and whether it matches
   what the validator expects"

Step 4: Fix at the source
  "the test fixture uses an expired token. either
   fix the fixture or adjust the test to use a
   valid token -- which is correct for this test case?"

Step 1: Get the full stack trace
  "paste the complete panic/error output"

Step 2: Identify the throwing line
  "the nil pointer is at handler.go:89 --
   user.GetProfile() on a nil user"

Step 3: Trace backward
  "how does 'user' get set? trace from the session
   lookup through to the handler. what happens when
   the session doesn't exist?"

Step 4: Fix with validation at the source
  "the session lookup returns nil without error
   when the session doesn't exist. add a nil check
   after lookup and return 401, not a panic"

Step 1: Find when it broke
  "this login test passed in CI last Wednesday.
   look at commits to the auth package since then"

Step 2: Identify the breaking change
  "commit abc123 changed the token validation to
   use a stricter time check. that's probably why
   tests with expired tokens now fail differently"

Step 3: Understand the intent
  "was the stricter validation intentional? read the
   commit message and PR description"

Step 4: Fix appropriately
  "the stricter validation was intentional for
   security. update the test fixtures to use valid
   tokens instead of reverting the validation change"

"use git bisect with the login test to find which
 exact commit broke it. mark the last known good
 commit as HEAD~20 and the bad commit as HEAD"

"this test fails about 1 in 10 runs. look for:
 - shared mutable state accessed without locks
 - goroutines that assume execution order
 - timeouts that might be too tight
 - test cleanup that runs before assertions"

"run the tests with the Go race detector:
 go test -race ./internal/checkout/
 and show me any race conditions it finds"

Step 1: Share the exact build output
  "here's the build error: [paste]"

Step 2: Let Claude diagnose
  "fix the build error and verify it compiles.
   address the root cause, don't suppress the error"

Step 3: Check for cascading effects
  "the fix compiles. run the tests to make sure
   nothing else broke"

"the build fails with a version conflict between
 library X and Y. read go.mod and figure out which
 version constraints are incompatible"

"use a subagent to investigate all the places
 where UserSession is created, modified, or
 invalidated. I need to understand the session
 lifecycle to debug the timeout issue"

After failed attempts, start clean:
  "the nil pointer in auth.go:47 is because
   sessionLookup returns nil when the session
   expired. I tried adding a nil check but the
   real issue is that the caller doesn't handle
   the expired case. fix the caller to check for
   expired sessions before calling GetProfile()"

"save your findings about the session timeout bug
 to progress.md: what we know, what we've tried,
 what the likely root cause is, and what to try next"

"commit the diagnostic logging we added so we don't
 lose it. message: 'add debug logging for session
 timeout investigation'"

Bad:  "add a nil check to stop the panic"
      (hides the bug, doesn't fix it)

Good: "why is the value nil? trace backward to find
       where the expected value should have been set"
      (finds the root cause)

Bad:  "try adding error handling here, and also
       here, and also change this timeout, and
       also try a different library version"
      (multiple changes, can't tell which one helped)

Good: "let's test one hypothesis: is the timeout
       too short? change only the timeout to 30s
       and run the test again"
      (one change, clear signal)

Bad:  "the test fails, make it pass"
      (Claude doesn't know what the error is)

Good: "the test fails with 'connection refused on
       localhost:5432'. the database container probably
       isn't running. check the test setup"
      (the error message contains the diagnosis)

Bad:  "the test expects 200 but gets 401, update
       the test to expect 401"
      (the test was correct, the code is broken)

Good: "the test expects 200 but gets 401. is the
       test wrong or is the code wrong? check what
       this endpoint should return for an authenticated
       user"
      (figure out which side is correct first)

Bad:  Attempt 1 failed → "try this instead" →
      Attempt 2 failed → "what about this?" →
      Attempt 3 failed → "maybe this?" →
      Context is full of noise, Claude is confused

Good: After 2 failed attempts →
      /clear →
      "I've been debugging the session timeout. Here's
       what I know: [findings]. The nil pointer at
       auth.go:47 happens because [reason]. Fix it by
       [approach based on what I learned]."