Agent skill
bug-debugging
Systematic bug debugging methodology, root cause analysis, and fix verification. Use when investigating and fixing bugs. (project)
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/bug-debugging
SKILL.md
Bug Debugging Methodology
Systematic Debugging Process
1. Reproduce the Bug
- Get exact steps to reproduce
- Note the environment (browser, OS, Node version)
- Identify if it's consistent or intermittent
- Document expected vs actual behavior
2. Gather Information
# Check logs
tail -f logs/app.log | grep -i error
# Check recent changes
git log --oneline -20
git diff HEAD~5
# Check environment
node --version
npm list --depth=0
3. Isolate the Problem
Binary Search Method
- If bug appeared recently, use
git bisect - Narrow down to specific commit
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
Component Isolation
- Disable features one by one
- Add logging at key points
- Test with minimal reproduction case
4. Root Cause Analysis
Ask "5 Whys"
- Why did the error occur?
- Why was that state possible?
- Why wasn't it validated?
- Why wasn't it caught in tests?
- Why wasn't it caught in review?
Common Bug Categories
| Category | Symptoms | Common Causes |
|---|---|---|
| Race Condition | Intermittent failures | Async timing, shared state |
| Memory Leak | Gradual slowdown | Unclosed connections, event listeners |
| Null Reference | Crash on access | Missing validation, async timing |
| Off-by-One | Wrong counts/indexes | Loop boundaries, array access |
| State Bug | Inconsistent UI/data | Stale state, mutation |
5. Debugging Tools
JavaScript/TypeScript
// Strategic console logging
console.log('[DEBUG] Function entry:', { args, state });
console.trace('Call stack');
console.time('operation'); // ... console.timeEnd('operation');
// Debugger statement
debugger; // Pauses in DevTools
// Node.js debugging
// node --inspect-brk app.js
Database Debugging
-- Check recent queries
EXPLAIN ANALYZE SELECT ...;
-- Check locks
SELECT * FROM pg_locks;
-- Check connections
SELECT * FROM pg_stat_activity;
6. Fix Verification
Before Committing
- Bug is reproducible without fix
- Bug is not reproducible with fix
- No regression in related functionality
- Edge cases are handled
- Error messages are helpful
Test Coverage
describe('Bug fix: #123', () => {
it('should handle the edge case that caused the bug', () => {
// Arrange: Set up the exact conditions
// Act: Trigger the bug scenario
// Assert: Verify correct behavior
});
});
7. Documentation
Commit Message Format
fix: Brief description of the fix
Root cause: [Explain why the bug occurred]
Solution: [Explain what the fix does]
Fixes #123
Common Debugging Patterns
Async/Promise Issues
// Add timeout to detect hanging promises
const withTimeout = (promise, ms) =>
Promise.race([
promise,
new Promise((_, reject) =>
setTimeout(() => reject(new Error('Timeout')), ms)
)
]);
State Debugging
// Track state changes
const debugState = (label, state) => {
console.log(`[${label}]`, JSON.stringify(state, null, 2));
return state;
};
Network Issues
# Check if service is reachable
curl -v http://localhost:3000/health
# Check DNS
nslookup api.example.com
# Check ports
netstat -tlnp | grep 3000
Prevention Checklist
- Add regression test for the bug
- Consider if similar bugs exist elsewhere
- Update documentation if needed
- Add input validation if applicable
- Improve error messages
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
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.
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.
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.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
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?