Diagnose

Diagnose Skill

Purpose

Investigation skill for bugs where the root cause is unknown. When you don't know why something is broken — just that it is — use /diagnose before reaching for /fix.

Key mechanism: spawns a fresh-context debugger subagent (Task tool) alongside a /review solve companion analysis. The main agent orchestrates, stays clean, and synthesizes results. Debug sessions persist in .claude/debug/<slug>.md so they survive context compaction and can be resumed.

Not for: applying a fix you already understand (use /fix), or quick one-line patches (use /quick).

When to Use

Usage

/diagnose "auth token not working"          # start new session
/diagnose --resume auth-token               # resume session by slug
/diagnose --list                            # show all active sessions
/diagnose --close auth-token               # mark session resolved
/diagnose --issue 42                        # pull symptoms from GitHub issue
/diagnose --issue 42 "login fails on iOS"   # issue + free-form description

Workflow

Step 1: Collect Symptoms

Ask the user for (or pull from gh issue view <N> if --issue provided):

• Expected — what should happen
• Actual — what is happening
• Error — exact error message or stack trace (if any)
• Timeline — when did this start, what changed recently
• Reproduction — minimal steps to reproduce

Generate a session slug: slugify the first 3-4 words of the description. Example: "auth token not working" → auth-token-not-working

Step 2: Triage Relevant Files

Before spawning the subagent, the main agent does a quick triage:

# Find files related to the error message or function names mentioned
grep -r "<error keyword>" src/ --include="*.py" -l
# Identify entry points, related test files, config

Build a file list (max ~20 files) with a one-line reason per file. This seeds the subagent with a focused starting point — not the whole codebase.

Step 3: Initialize Session File

Write .claude/debug/<slug>.md:

# Diagnose Session: <title>

**State:** active
**Created:** YYYY-MM-DD HH:MM
**Iteration:** 1
**Issue:** #N or —

## Symptoms

- Expected: ...
- Actual: ...
- Error: ...
- Timeline: ...
- Reproduction: ...

## Relevant Files

- `path/to/file.py` — reason it's relevant

## Hypotheses

### H1: <description>

- **Test:** <how to verify>
- **Result:** pending
- **Evidence:** —

## Root Cause

<!-- Filled when found -->

## Suggested Fix

<!-- Filled when root cause is confirmed -->

Step 4: Parallel Investigation

Launch both simultaneously:

A. Debugger subagent (Task tool):

type: general-purpose
model: sonnet
prompt: |
  You are a debugger. Your job is to find the root cause of a bug.
  DO NOT modify any source code files — read-only investigation only.

  Read the session file at .claude/debug/<slug>.md for symptoms and file list.
  Then:
  1. Read all listed relevant files
  2. Form 2-3 hypotheses about the root cause
  3. Test each hypothesis: run existing tests, grep for related code, trace execution paths
  4. For each hypothesis: document Test, Result (confirmed/rejected), Evidence
  5. Write your findings back to the session file under ## Hypotheses
  6. If you find the root cause, fill ## Root Cause and ## Suggested Fix

  Model escalation: if sonnet-level investigation exhausts hypotheses after 2 attempts,
  note "Escalate to opus" in the session file.

B. Companion analysis (/review solve):

/review solve "<symptom description>" --context .claude/debug/<slug>.md

The companion gives an architectural second opinion: is this a design smell, a missing invariant, or a pure implementation bug? Runs concurrently — no need to wait for the subagent.

Step 5: Synthesize Results

Once both complete, the main agent:

1. Reads the updated session file (subagent findings)
2. Reads the companion analysis output
3. Synthesizes: code-level evidence (subagent) + architectural perspective (companion)
4. Reports a clear summary to the user:
   • What each hypothesis found
   • Whether root cause is confirmed
   • Confidence level (confirmed / suspected / unclear)

Step 6: Evaluate and Iterate

Root cause confirmed → proceed to Step 7.

All hypotheses rejected:

• Ask the user for additional context (logs, reproduction details, recent changes)
• Update the session file with new context
• Increment Iteration counter
• Iteration 1–2: Spawn a new subagent iteration (model: sonnet) with updated session state
• Iteration 3 (all hypotheses exhausted): Automatically escalate — spawn an Opus subagent:

  type: general-purpose
  model: opus
  prompt: |
    Sonnet-level investigation exhausted all hypotheses after 2 iterations.
    Read the full session file at .claude/debug/<slug>.md including all rejected hypotheses.
    Use deeper reasoning to identify what was missed. Focus on non-obvious causes:
    timing issues, environment differences, subtle state mutations, implicit contracts.
    Document new hypotheses and test them. Update ## Hypotheses, ## Root Cause, ## Suggested Fix.
  

  If Opus also cannot find the root cause, ask the user for direct manual investigation input.

Step 7: Hand Off

Present the root cause to the user:

Root cause: <one-sentence summary>
Evidence: <key findings from hypothesis testing>
Confidence: confirmed | suspected

Suggested next step:
  - Small fix (1-3 files): /fix "<root cause summary>"
  - Larger change:         /implementation "<root cause summary>"

Do NOT auto-invoke /fix — the user decides when and how to proceed.

Step 8: Close Session

Via --close <slug> (or automatically triggered after /fix confirms resolution):

**State:** resolved
**Resolved:** YYYY-MM-DD
**Fix:** <commit SHA or PR #>

Session files are kept for future reference. They're gitignored (.claude/debug/ is in .gitignore).

--list and --resume

--list

/diagnose --list

Glob .claude/debug/*.md, parse State: and title from each file. Display as a table: slug | state | created | issue.

--resume <slug>

/diagnose --resume auth-token-not-working

Read the session file, display current state and previous hypotheses. Spawn a new subagent iteration with the full session context (including rejected hypotheses). The subagent uses rejected hypotheses to avoid repeating dead ends.

Session File Location

.claude/debug/<slug>.md — gitignored, peer to .claude/plans/ and .claude/tasks/.

The directory is already excluded in .gitignore. Do not commit debug sessions.

Related Skills

• /fix — apply the fix once root cause is known (natural next step after /diagnose)
• /implementation — larger fixes requiring full TDD and PR workflow
• /review solve — companion analysis used internally in Step 4
• /review changes — review code changes after /fix applies the fix