From charon-fan-agent-playbook
Diagnoses and resolves code bugs, errors, and unexpected behavior via systematic phases: reproduce, isolate, root cause analysis, hypothesis testing, fix, and verify. Uses bash, grep, git for investigation.
npx claudepluginhub zhaono1/agent-playbookThis skill is limited to using the following tools:
An advanced debugging specialist that helps diagnose and resolve code issues systematically.
Systematically debugs code errors, exceptions, and failures using structured workflow: gather info, classify error types, isolate via binary search and logging.
Provides a five-step systematic debugging workflow: reproduce the bug, isolate the cause, form hypotheses, implement fixes, and verify results. For errors, broken code, or unexpected behavior.
Performs systematic debugging with 5-step process: reproduce, isolate, identify root cause, fix, and verify issues using Read, Grep, Glob, Bash, Edit tools.
Share bugs, ideas, or general feedback.
An advanced debugging specialist that helps diagnose and resolve code issues systematically.
Activates when you:
Reproduce the issue
Gather context
# Check recent changes
git log --oneline -10
# Check error logs
tail -f logs/error.log
# Check environment
env | grep -i debug
Locate the error source
Narrow down scope
| Category | Symptoms | Investigation Steps |
|---|---|---|
| Null/Undefined | "Cannot read X of undefined" | Trace the variable origin |
| Type Errors | "X is not a function" | Check actual vs expected type |
| Async Issues | Race conditions, timing | Check promise handling, async/await |
| State Issues | Stale data, wrong state | Trace state mutations |
| Network | Timeouts, connection refused | Check endpoints, CORS, auth |
| Environment | Works locally, not in prod | Compare env vars, versions |
| Memory | Leaks, OOM | Profile memory usage |
| Concurrency | Deadlocks, race conditions | Check locks, shared state |
For each potential cause:
# Find recently modified files
find . -type f -mtime -1 -name "*.js" -o -name "*.ts" -o -name "*.py"
# Grep for error patterns
grep -r "ERROR\|FATAL\|Exception" logs/
# Search for suspicious patterns
grep -r "TODO\|FIXME\|XXX" src/
# Check for console.log left in code
grep -r "console\.log\|debugger" src/
JavaScript/TypeScript:
# Run with debug output
NODE_DEBUG=* node app.js
# Check syntax
node -c file.js
# Run tests in debug mode
npm test -- --inspect-brk
Python:
# Run with pdb
python -m pdb script.py
# Check syntax
python -m py_compile script.py
# Verbose mode
python -v script.py
Go:
# Race detection
go run -race main.go
# Debug build
go build -gcflags="-N -l"
# Profile
go test -cpuprofile=cpu.prof
# When you don't know where the bug is:
def process():
step1()
step2()
step3()
step4()
# Comment out half:
def process():
step1()
# step2()
# step3()
# step4()
# If bug disappears, uncomment half of commented:
def process():
step1()
step2()
# step3()
# step4()
# Continue until you isolate the bug
// Before (mysterious failure):
async function getUser(id: string) {
const user = await db.find(id);
return transform(user);
}
// After (with logging):
async function getUser(id: string) {
console.log('[DEBUG] getUser called with id:', id);
const user = await db.find(id);
console.log('[DEBUG] db.find returned:', user);
const result = transform(user);
console.log('[DEBUG] transform returned:', result);
return result;
}
// Complex code with bug:
function processBatch(items, options) {
// 100 lines of complex logic
}
// Create minimal reproduction:
function processBatch(items, options) {
console.log('Items:', items.length);
console.log('Options:', options);
// Test with minimal data
return processBatch([items[0]], options);
}
| Error | Likely Cause | Solution |
|---|---|---|
Cannot read property 'X' of undefined | Accessing property on null/undefined | Add null check, use optional chaining |
X is not a function | Wrong type, shadowing | Check typeof, verify import |
Unexpected token | Syntax error | Check line before error, validate syntax |
Module not found | Import path wrong | Check relative path, verify file exists |
EADDRINUSE | Port already in use | Kill existing process, use different port |
Connection refused | Service not running | Start service, check port |
Timeout | Request too slow | Increase timeout, check network |
Generate a debug report:
python scripts/debug_report.py <error-message>
references/checklist.md - Debugging checklistreferences/patterns.md - Common debugging patternsreferences/errors.md - Error message reference