diagnose — Diagnostic Debugging

• Trigger: /diagnose or keywords "diagnose this", "debug this", "what's wrong with"
• Best for: Bug debugging, performance regressions, anomaly investigation
• Not for: Pure exploration, new features, code review

Overview

diagnose is Claude Code's general-purpose debugging Skill. It follows a rigorous diagnostic loop: "Reproduce → Narrow → Hypothesize → Instrument → Fix → Regression-test", ensuring every bug is systematically located and resolved.

Trigger Conditions

diagnose auto-triggers when you:

• Describe a bug or unexpected behavior
• Mention a performance regression or slowdown
• Say something is "broken" or "not working"
• Use the /diagnose command

Examples

Example 1: API Latency Spike

/diagnose The /api/users endpoint P99 latency jumped from 50ms to 500ms

Claude will:

1. Ask about recent deployments
2. Check for N+1 queries
3. Look for missing indexes or slow queries
4. Check for cache invalidation

Example 2: Frontend Rendering Bug

/diagnose React list page goes blank after scrolling to bottom, Chrome latest

Claude will:

1. Determine if it's a render crash or data issue
2. Inspect virtual list / infinite scroll implementation
3. Check for memory leaks or key issues

Example 3: CI Build Failure

/diagnose CI build suddenly failing, works locally, error: 'Module not found'

Example 4: Data Inconsistency

/diagnose Order status shows 'shipped' but tracking info is empty, intermittent

Example 5: Flaky Test

/diagnose UsersService.test.ts fails intermittently, about 30% of runs

Workflow

1. Reproduce — Collect reproduction conditions, frequency, environment
2. Narrow — Use bisection, git bisect, or logs to locate suspicious code
3. Hypothesize — Propose verifiable cause hypotheses based on code logic
4. Instrument — Add logging/breakpoints/monitoring to validate
5. Fix — Apply fix after confirming root cause
6. Regression-test — Ensure fix doesn't introduce new issues

Notes

• Provide reproduction steps and environment info for faster diagnosis
• For hard-to-reproduce issues, describe trigger probability and known patterns
• Sanitize any sensitive production data
• This is not a code review tool — use /review instead
• Complex performance issues may need actual profiling data

Related Skills

• tdd — Write tests after fixing to prevent regressions
• review — Review changes after the fix
• simplify — Clean up legacy complexity after fixing