From ai-toolkit
Provides structured runbook for debugging backend service issues including API errors, performance degradation, crashes, and data inconsistencies. Uses checklists, log greps, git bisect, and reproduction steps.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-toolkit:service-debuggingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Structured approach to investigating and fixing service issues. Symptoms in, root cause out.
Structured approach to investigating and fixing service issues. Symptoms in, root cause out.
Before touching code, collect:
Run these first — they catch 80% of issues:
# Recent deploys (did someone push something?)
git log --oneline -10
# Service health
curl -s http://localhost:8080/health | jq .
# Recent errors in logs
grep -i "error\|exception\|fatal" logs/app.log | tail -20
# Database connectivity
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"
# Environment variables (missing or wrong?)
env | grep -i "DB_\|API_\|SECRET_" | sort
| Symptom | Check First |
|---|---|
| 500 errors | Stack trace in logs → find the throwing line |
| 404 errors | Route registration → is the controller loaded? |
| 401/403 errors | Auth config → is @Secured correct? Token valid? |
| Slow response | Database → run EXPLAIN on the slow query |
| Timeout | External service → is the downstream API responding? |
| Data missing | Soft delete → is deleted_at set? Wrong query filter? |
| Service won't start | Bean creation → check @Factory and @Singleton wiring |
Use git bisect if it's a regression:
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Test each commit until you find the one that broke it
Use grep to find related code:
# Find where the error message comes from
grep -r "error message text" --include="*.kt" src/
# Find all callers of a broken function
grep -r "functionName" --include="*.kt" src/
See
common-issues.mdfor a catalog of frequently seen bugs and their fixes.
deleted_at IS NULL in your queries.npx claudepluginhub c0x12c/ai-toolkit --plugin ai-toolkitSystematically debugs issues via reproduction steps, isolation techniques like git bisect, log/stack trace analysis, and common error pattern fixes. For bugs, incidents, troubleshooting.
Applies systematic root-cause analysis to debug errors, test failures, and unexpected behavior across frontend, backend, database, network, and performance.
Investigates and diagnoses software bugs using scientific method: observe symptoms, hypothesize causes, test with logging/Bash/Grep/Glob, analyze without fixing. Use before /fix for root cause.