debugging-strategies
A structured approach to debugging using the scientific method and root cause analysis.
Install
mkdir -p .claude/skills/debugging-strategies && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2609" && unzip -o skill.zip -d .claude/skills/debugging-strategies && rm skill.zipInstalls to .claude/skills/debugging-strategies
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
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.Key capabilities
- →Implementation of scientific method-based debugging
- →Generation of minimal reproduction cases
- →Structured environment data collection
- →Rubber duck debugging facilitation
- →Systematic hypothesis documentation
How it works
It mandates a step-by-step framework that forces documentation of observations, hypotheses, and experimental results before suggesting solutions.
Inputs & outputs
When to use debugging-strategies
- →Isolate production bugs
- →Analyze performance bottlenecks
- →Document reproduction steps
- →Debug memory leaks
About this skill
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
## 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
## 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
## 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
## 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
## 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
## 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
## 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
- 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
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
## 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)
When not to use it
- →When quick patches are required without long-term root cause analysis
- →For trivial UI styling issues that do not require logical investigation
Limitations
- →Requires user patience to complete all steps
- →Cannot solve bugs that defy standard logic (e.g., hardware instability)
- →Depends on user input for environment details
How it compares
It enforces a rigorous, reproducible process rather than relying on LLM guesswork or superficial code changes.
Compared to similar skills
debugging-strategies side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| debugging-strategies (this skill) | 3 | 8mo | Review | Intermediate |
| python-testing-patterns | 77 | 5mo | Review | Intermediate |
| chrome-devtools | 41 | 10mo | Review | Intermediate |
| bats | 9 | 10mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by wshobson
View all by wshobson →You might also like
python-testing-patterns
wshobson
Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.
chrome-devtools
mrgoonie
Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.
bats
OleksandrKucherenko
Bash Automated Testing System (BATS) for TDD-style testing of shell scripts. Use when: (1) Writing unit or integration tests for Bash scripts, (2) Testing CLI tools or shell functions, (3) Setting up test infrastructure with setup/teardown hooks, (4) Mocking external commands (curl, git, docker), (5) Generating JUnit reports for CI/CD, (6) Debugging test failures or flaky tests, (7) Implementing test-driven development for shell scripts.
browser-daemon
noiv
Persistent browser automation via Playwright daemon. Keep a browser window open and send it commands (navigate, execute JS, inspect console). Perfect for interactive debugging, development, and testing web applications. Use when you need to interact with a browser repeatedly without opening/closing it.
performance-profiling
davila7
Performance profiling principles. Measurement, analysis, and optimization techniques.
obsidian-local-dev-loop
jeremylongshore
Configure Obsidian plugin development with hot-reload and fast iteration. Use when setting up development workflow, configuring test vaults, or establishing a rapid development cycle. Trigger with phrases like "obsidian dev loop", "obsidian hot reload", "obsidian development workflow", "develop obsidian plugin".