Debugging Strategies
Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance issues, or unexpected behavior.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Debugging Strategies when an AI agent needs a reusable SKILL.md workflow for this job: Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance issues, or unexpected behavior.
When not to use it
Skip Debugging Strategies when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/debugging-strategies # Save SKILL.md to ~/.claude/skills/debugging-strategies/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/debugging-strategies/SKILL.md. For a shared project, commit the folder at .claude/skills/debugging-strategies/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Debugging Strategies skill for this task: Tracking down elusive bugs. Confirm any required inputs or files before making changes.
What supports this recommendation?
90/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 100/100
- Practical detail
- 100/100
- Source evidence
- 63/100
- Source signals
- 80/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Debugging Strategies
Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.
## When to Use This Skill
- Tracking down elusive bugs - Investigating performance issues - Understanding unfamiliar codebases - Debugging production issues - Analyzing crash dumps and stack traces - Profiling application performance - Investigating memory leaks - Debugging distributed systems
## Core Principles
### 1. The Scientific Method
**1. Observe**: What's the actual behavior? **2. Hypothesize**: What could be causing it? **3. Experiment**: Test your hypothesis **4. Analyze**: Did it prove/disprove your theory? **5. Repeat**: Until you find the root cause
### 2. Debugging Mindset
**Don't Assume:**
- "It can't be X" - Yes it can - "I didn't change Y" - Check anyway - "It works on my machine" - Find out why
**Do:**
- Reproduce consistently - Isolate the problem - Keep detailed notes - Question everything - Take breaks when stuck
### 3. Rubber Duck Debugging
Explain your code and problem out loud (to a rubber duck, colleague, or yourself). Often reveals the issue.
## Systematic Debugging Process
### Phase 1: Reproduce
```markdown ## Reproduction Checklist
1. **Can you reproduce it?** - Always? Sometimes? Randomly? - Specific conditions needed? - Can others reproduce it?
2. **Create minimal reproduction** - Simplify to smallest example - Remove unrelated code - Isolate the problem
3. **Document steps** - Write down exact steps - Note environment details - Capture error messages ```
### Phase 2: Gather Information
```markdown ## Information Collection
1. **Error Messages** - Full stack trace - Error codes - Console/log output
2. **Environment** - OS version - Language/runtime version - Dependencies versions - Environment variables
3. **Recent Changes** - Git history - Deployment timeline - Configuration changes
4. **Scope** - Affects all users or specific ones? - All browsers or specific ones? - Production only or also dev? ```
### Phase 3: Form Hypothesis
```markdown ## Hypothesis Formation
Based on gathered info, ask:
1. **What changed?** - Recent code changes - Dependency updates - Infrastructure changes
2. **What's different?** - Working vs broken environment - Working vs broken user - Before vs after
3. **Where could this fail?** - Input validation - Business logic - Data layer - External services ```
### Phase 4: Test & Verify
```markdown ## Testing Strategies
1. **Binary Search** - Comment out half the code - Narrow down problematic section - Repeat until found
2. **Add Logging** - Strategic console.log/print - Track variable values - Trace execution flow
3. **Isolate Components** - Test each piece separately - Mock dependencies - Remove complexity
4. **Compare Working vs Broken** - Diff configurations - Diff environments - Diff data ```
Before selecting debugging tools or performing bisect, differential, trace, or memory analysis, read `references/tools-and-techniques.md`.
## Debugging Patterns by Issue Type
### Pattern 1: Intermittent Bugs
```markdown ## Strategies for Flaky Bugs
1. **Add extensive logging** - Log timing information - Log all state transitions - Log external interactions
2. **Look for race conditions** - Concurrent access to shared state - Async operations completing out of order - Missing synchronization
3. **Check timing dependencies** - setTimeout/setInterval - Promise resolution order - Animation frame timing
4. **Stress test** - Run many times - Vary timing - Simulate load ```
### Pattern 2: Performance Issues
```markdown ## Performance Debugging
1. **Profile first** - Don't optimize blindly - Measure before and after - Find bottlenecks
2. **Common culprits** - N+1 queries - Unnecessary re-renders - Large data processing - Synchronous I/O
3. **Tools** - Browser DevTools Performance tab - Lighthouse - Python: cProfile, line_profiler - Node: clinic.js, 0x ```
### Pattern 3: Production Bugs
```markdown ## Production Debugging
1. **Gather evidence** - Error tracking (Sentry, Bugsnag) - Application logs - User reports - Metrics/monitoring
2. **Reproduce locally** - Use production data (anonymized) - Match environment - Follow exact steps
3. **Safe investigation** - Don't change production - Use feature flags - Add monitoring/logging - Test fixes in staging ```
## Best Practices
1. **Reproduce First**: Can't fix what you can't reproduce 2. **Isolate the Problem**: Remove complexity until minimal case 3. **Read Error Messages**: They're usually helpful 4. **Check Recent Changes**: Most bugs are recent 5. **Use Version Control**: Git bisect, blame, history 6. **Take Breaks**: Fresh eyes see better 7. **Document Findings**: Help future you 8. **Fix Root Cause**: Not just symptoms
## Common Debugging Mistakes
- **Making Multiple Changes**: Change one thing at a time - **Not Reading Error Messages**: Read the full stack trace - **Assuming It's Complex**: Often it's simple - **Debug Logging in Prod**: Remove before shipping - **Not Using Debugger**: console.log isn't always best - **Giving Up Too Soon**: Persistence pays off - **Not Testing the Fix**: Verify it actually works
## Quick Debugging Checklist
```markdown ## When Stuck, Check:
- [ ] Spelling errors (typos in variable names) - [ ] Case sensitivity (fileName vs filename) - [ ] Null/undefined values - [ ] Array index off-by-one - [ ] Async timing (race conditions) - [ ] Scope issues (closure, hoisting) - [ ] Type mismatches - [ ] Missing dependencies - [ ] Environment variables - [ ] File paths (absolute vs relative) - [ ] Cache issues (clear cache) - [ ] Stale data (refresh database) ```
Intended uses
- Tracking down elusive bugs
- Investigating performance issues
- Understanding unfamiliar codebases
- Debugging production issues
- Analyzing crash dumps and stack traces
- Profiling application performance
- Investigating memory leaks
- Debugging distributed systems
Implementation notes
- Reproduce First: Can't fix what you can't reproduce
- Isolate the Problem: Remove complexity until minimal case
- Read Error Messages: They're usually helpful
- Check Recent Changes: Most bugs are recent
- Use Version Control: Git bisect, blame, history
- Take Breaks: Fresh eyes see better
- Document Findings: Help future you
- Fix Root Cause: Not just symptoms
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.