/debug

name: debug
description: "Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation."
user-invocable: true
effort: medium
argument-hint: "[symptom]"
agent: debugger
context: fork
allowed-tools: Bash, Read, Grep

Debug Helper

$ARGUMENTS

Systematic debugging for application issues.

Project context

• Recent logs: !`docker compose logs --tail 20 2>/dev/null || tail -20 logs/*.log 2>/dev/null || echo "no-logs-found"`

Automated Error Parsing

Pipe error output through the error parser for structured diagnosis:

# Pipe from failing command
your_command 2>&1 | python3 ${CLAUDE_SKILL_DIR}/scripts/error-parser.py

# Or from a log file
cat /var/log/app/error.log | python3 ${CLAUDE_SKILL_DIR}/scripts/error-parser.py

The script outputs JSON with:

• **language**: detected language (python/node/go/php)
• **error_type**: extracted error class (e.g., ModuleNotFoundError)
• **message**: the error message text
• **category**: classification (import, reference, type, connection, timeout, memory, permission, syntax)
• **stack_frames**: parsed file/line/function from the stack trace
• **files_to_check**: unique files from the trace, ordered by relevance
• **common_causes**: likely root causes for this error category

Use the parsed output to focus investigation on the right files and hypotheses.

---

Methodology — The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Quick patches mask underlying issues. Complete each phase before proceeding to the next.

Phase 1 — Root Cause Investigation

Read error messages and stack traces completely. Reproduce reliably (or gather more data — don't guess). Check recent changes (`git diff`, new deps, config). For multi-component systems: log boundary in/out at each layer, identify WHERE it breaks before WHY.

Phase 2 — Pattern Analysis

Find similar working code in the same codebase. Compare against references **completely**, not skimming. List every difference, however small.

Phase 3 — Hypothesis & Testing

Form a single hypothesis ("X is the root cause because Y"). Test minimally — smallest possible change, one variable at a time. Verify before continuing — if it didn't work, form a NEW hypothesis. Don't stack fixes on top of fixes.

Phase 4 — Implementation

Write a failing test case FIRST (use `/tdd`). Implement single fix at root cause. No "while I'm here" improvements.

"5 Whys" — depth gate

Ask "Why?" at least 5 times to find the real issue. Stop at the first plausible answer = symptom fixing. Example: crash → null pointer → user object null → API 404 → invalid user ID → **frontend allowed negative IDs** (root cause).

Architecture escalation (3+ failed fixes)

If three hypotheses failed and each fix reveals new shared state in different places, the architecture is wrong, not your hypothesis. STOP. Discuss with user before more attempts.

---

Debugging Workflow

1. Check Logs

# Application logs (auto-detect environment)
# Docker:
docker compose logs --tail 100 {service} 2>&1 | grep -i error

# Bare metal / systemd:
journalctl -u {service} --since "1 hour ago" | grep -i error

# Log files:
tail -100 logs/app.log | grep -i error

2. Check Service Health

# Docker environment
docker compose ps

# Process check
ps aux | grep -E "(node|python|java|php)" | grep -v grep

# HTTP health endpoints
curl -sf http://localhost:{port}/health

3. Interactive Debug

# Python
python3 -c "import module; print(module.function('test'))"

# Node.js
node -e "const m = require('./module'); console.log(m.fn('test'))"

# PHP
php -r "require 'vendor/autoload.php'; echo MyClass::method('test');"

4. Database Checks

# PostgreSQL
psql -U postgres -c "SELECT version();"

# MySQL
mysql -e "SELECT VERSION();"

# Redis
redis-cli ping && redis-cli info memory

# MongoDB
mongosh --eval "db.runCommand({ping:1})"

Common Debug Scenarios

API Returns 500

# Check server logs for stack traces
grep -A5 "Traceback\|Error\|Exception" logs/app.log

Slow Performance

# Resource usage
top -bn1 | head -20     # CPU/memory
iostat -x 1 3            # Disk I/O
ss -tlnp                 # Open connections

Connection Issues

# Test connectivity
curl -I http://localhost:{port}
nc -zv {host} {port}

Parallel Hypothesis Debugging (Agent Teams)

For complex bugs (open >1h, unclear root cause), spawn teammates to investigate competing hypotheses:

Create an agent team to debug this issue:
- Teammate 1 (debugger): "Investigate if [bug] is caused by [hypothesis A: database issue].
  Check logs, connection pools, timeouts, query performance."
  Use Opus.
- Teammate 2 (debugger): "Investigate if [bug] is caused by [hypothesis B: race condition].
  Look for async issues, locking, concurrency, shared state."
  Use Opus.
- Teammate 3 (debugger): "Investigate if [bug] is caused by [hypothesis C: configuration drift].
  Compare env vars, config files, recent changes, dependency versions."
  Use Opus.
Have them talk to each other to challenge each other's theories.
Report consensus when done.

Common Rationalizations

| Excuse | Why It's Wrong | |--------|----------------| | "It works on my machine" | Environment differences are the #1 cause of production bugs — reproduce in prod-like env | | "It must be a library bug" | 95% of the time it's your code — exhaust local hypotheses first | | "I'll just add more logging and wait" | Passive debugging wastes hours — form a hypothesis and test it actively | | "The error message says X, so it must be X" | Error messages often describe symptoms, not root causes — trace the full chain | | "It only happens sometimes, probably a fluke" | Intermittent bugs are race conditions or state leaks — they get worse, not better |

Debug Checklist

• [