7 Techniques to Debug Claude Code

---
name: source-of-truth
description: Research best practices and write a persistent source of truth file for a feature. Use when starting a new feature, debugging a complex problem, or when context keeps getting lost between sessions.
argument-hint: "[feature-name]"
disable-model-invocation: true
---

# Build a Source of Truth File

Create a persistent plan file that survives context compression. This file becomes the single reference point for how a feature should work, what's been tried, and what we know.

## Steps

1. **Research best practices.** Search the web for how `$ARGUMENTS` is typically implemented. Check official docs, find real-world examples, and identify common patterns and pitfalls.

2. **Read the codebase.** Find all files related to `$ARGUMENTS` in this project. Understand the current implementation, architecture, and dependencies.

3. **Write the source of truth file** to `docs/plans/$ARGUMENTS.md` with these sections:

# [Feature Name] — Source of Truth

## Best Practices
Patterns and approaches from research. What the community recommends.

## How It Should Work
End-to-end description of the correct behavior. Expected inputs, outputs, edge cases.

## Files Involved
Each file that touches this feature and its responsibility.

## What We've Tried
Every approach attempted so far and why it failed. Add to this section as work continues.

## What Works
Things we know are correct and should not be changed.

4. **Report back** with a summary of what you found and wrote.

## Important

- If `docs/plans/$ARGUMENTS.md` already exists, read it first and update it rather than overwriting.
- Be specific in the "What We've Tried" section. Include file names, line numbers, and error messages.
- The "What Works" section prevents regressions. Don't skip it.

---
name: unstuck
description: Break out of a debugging loop. Reads the source of truth file if one exists, examines the full data flow, and proposes the right solution rather than another quick fix. Use when you've been going in circles or when fixes keep breaking other things.
argument-hint: "[what you're stuck on]"
disable-model-invocation: true
---

# Get Unstuck

Stop fixing the symptom. Think holistically about what's actually going wrong.

## Steps

1. **Check for a source of truth file.** Look in `docs/plans/` for any file related to `$ARGUMENTS`. If one exists, read it first. Pay attention to the "What We've Tried" section so you don't repeat failed approaches.

2. **Read the full data flow.** Don't just look at the file with the error. Trace the complete flow end to end. Read every file involved in `$ARGUMENTS`. Understand the architecture, not just the stack trace.

3. **Identify the real problem.** Ask yourself:
 - Is this a symptom or the root cause?
 - Would fixing this break something downstream?
 - Is there a wrong assumption buried in the code?
 - Are we patching around a design problem?

4. **Propose the right solution.** Not the fastest fix. The correct, scalable one. Explain:
 - What the root cause actually is
 - Why previous attempts failed (if applicable)
 - What the right fix looks like and why it won't break other things
 - What files need to change

5. **Update the source of truth file** if one exists. Add what you found to the "What We've Tried" section.

## Important

- Do NOT start editing files immediately. Think first, propose, then implement only after explaining your approach.
- If you've already tried fixing this more than twice, something is wrong with the approach, not the implementation. Step back further.
- Use "think hard" if the problem is complex. Take the time to reason through it.

---
name: review
description: Review the current changes like a senior engineer would. Checks the git diff for bugs, edge cases, missing error handling, and things that might break downstream. Use after implementing a feature or fix, before committing.
context: fork
agent: Explore
---

# Code Review

Review the current uncommitted changes with fresh eyes. You have no context about why these changes were made. Judge them purely on quality.

## Steps

1. **Read the diff.** Run `git diff` to see all uncommitted changes. If there are staged changes, also run `git diff --cached`.

2. **Understand what changed.** For each modified file, read enough of the surrounding code to understand the context. Don't just look at the changed lines.

3. **Review for these issues:**

 **Correctness**
 - Does the logic actually do what it appears to intend?
 - Are there off-by-one errors, null checks, or race conditions?
 - Does it handle edge cases (empty inputs, large inputs, concurrent access)?

 **Side effects**
 - Could these changes break something in another part of the codebase?
 - Are there callers of modified functions that might not expect the new behavior?
 - Do database or API contract changes affect other consumers?

 **Quality**
 - Is the approach the right one, or is it papering over a deeper issue?
 - Is there duplicated logic that should be extracted?
 - Are error messages helpful for debugging?

 **Missing pieces**
 - Are there tests for the new behavior?
 - Are there edge cases that aren't covered?
 - Is there error handling that should exist but doesn't?

4. **Report your findings.** Be specific. Reference file names and line numbers. For each issue, explain:
 - What the problem is
 - Why it matters
 - What the fix should be

If the changes look good, say so. Don't invent problems.