Agent skill
debugging
Hypothesis-driven debugging with systematic investigation. Identifies root causes, creates minimal reproductions, and implements fixes. Use when investigating errors, bugs, crashes, or unexpected behavior.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/debugging-1ambda-dataops-platform-4
SKILL.md
Debugging
Systematic debugging using hypothesis testing and root cause analysis.
When to Use
- Error investigation (exceptions, crashes)
- Unexpected behavior diagnosis
- Performance issue root cause
- Integration/dependency failures
MCP Workflow
# 1. Get code at error location
serena.find_symbol(name_path="ErrorClass/method", include_body=True)
# 2. Trace call chain
serena.find_referencing_symbols(name_path="ErrorClass/method")
# 3. Search for similar patterns
serena.search_for_pattern("null.*check|error.*handling", relative_path="src/")
# 4. Check past similar issues
claude-mem.search(query="<error-type>", project="<project>")
# 5. Framework error handling
context7.get-library-docs("<framework>", topic="exception handling")
Workflow
1. Observe
- Error message and stack trace
- Steps to reproduce
- When did it start? (recent changes?)
- Scope (one user? all?)
2. Hypothesize
Based on: [observation]
Hypothesis: [proposed cause]
Test: [how to verify]
3. Test
serena.find_symbol("SuspectedClass/method", include_body=True)
serena.find_referencing_symbols("SuspectedCause")
# Log analysis, local reproduction
4. Fix
1. Write failing test that reproduces bug
2. Implement minimal fix
3. Verify test passes
4. Run full test suite
5. Prevent
- Add edge case tests
- Improve validation
- Update documentation
Common Patterns
Null/Undefined
Symptoms: NullPointerException, "undefined is not a function" Investigate:
- Find where null originates
- Trace back through call chain
- Check data presence assumptions
Race Condition
Symptoms: Intermittent, works in debug mode Red flags:
- Shared mutable state
- Missing synchronization
- Execution order assumptions
Data Inconsistency
Investigate:
- Trace data flow source to error
- Check transformation logic
- Verify cache invalidation
Investigation Techniques
Git Bisect
git bisect start
git bisect bad
git bisect good <commit>
# Test middle commit, mark good/bad
git bisect reset
Stack Trace Analysis
Start at bottom (entry point)
Move up to error line
Examine code at that line
Check what could be null/invalid
Divide and Conquer
A -> B -> C -> D (output wrong)
Check B: correct? -> problem in C or D
wrong? -> problem in A or B
Output Format
## Bug: [Title]
### Symptoms
- Error: [message]
- Location: `file:line`
### Investigation
**Hypothesis 1:** [description]
- Test: [method]
- Result: Confirmed / Ruled Out
### Root Cause
[Identified cause] at `file:line`
### Fix
[Description]
### Prevention
- [ ] Test added
- [ ] Similar patterns checked
Checklist
- Can reproduce consistently
- Stack trace analyzed
- Root cause identified (not just symptom)
- Failing test written
- Fix implemented
- Full test suite passes
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?