debug

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.