Agent skill
debug
Unified debugging workflow enforcing root cause protocol. Investigate → Understand → Reason → Fix. Use when debugging bugs, errors, or unexpected behavior.
Install this agent skill to your Project
npx add-skill https://github.com/johnlindquist/claude/tree/main/skills/debug
SKILL.md
Debug - Root Cause Debugging Workflow
Complete debugging workflow that enforces root cause analysis: Investigate → Understand → Reason → Fix.
Overview
Debug combines multiple debugging approaches:
- Codebase investigation - Search for relevant code
- GitHub issues search - Find known issues and workarounds
- Multi-framework reasoning - Apply systematic thinking
- Fix generation - Specific recommendations with code
Prerequisites
# Gemini CLI for AI analysis
pip install google-generativeai
export GEMINI_API_KEY=your_api_key
# gh CLI for GitHub issue search
brew install gh
gh auth login
Debugging Workflows
Full Debug (Recommended for Complex Issues)
# Phase 1: Investigate codebase
rg -l "error pattern" --type ts
rg "relevant_function" -A 10 -B 5
# Phase 2: Search GitHub for known issues
gh search issues "error message" --repo owner/repo --limit 10
gh issue view 123 --repo owner/repo
# Phase 3: Reason about root cause
gemini -m pro -o text -e "" "Given this error and code context, what is the root cause?
Error: [error message]
Code:
\$(cat src/file.ts)
Investigation findings:
- [finding 1]
- [finding 2]
Apply first principles, systematic, and critical thinking frameworks."
# Phase 4: Generate fix
gemini -m pro -o text -e "" "Based on root cause: [cause]
Provide:
1. Specific code fix
2. Before/after code
3. How to verify
4. How to prevent"
Quick Debug (Simple Issues)
# Skip deep reasoning, focus on investigation + fix
rg "error pattern" --type ts -A 5 -B 5
gemini -m pro -o text -e "" "Debug this quickly:
Problem: [description]
Error: [message]
Code:
\$(cat src/problematic-file.ts)
Give me the root cause and fix in 3 sentences."
Debug with Context (Known Files)
# When you already know which files are involved
gemini -m pro -o text -e "" "Debug using these files:
Problem: [description]
File 1:
\$(cat src/file1.ts)
File 2:
\$(cat src/file2.ts)
Provide:
1. Root cause
2. Specific fix with line numbers
3. Verification steps"
Comprehensive Diagnosis (Complex Issues)
# Parallel investigation of multiple sources
# Terminal 1: Codebase search
rg "error" --type ts --stats > /tmp/codebase.txt &
# Terminal 2: GitHub issues
gh search issues "error" --limit 20 > /tmp/github.txt &
# Terminal 3: Git history
git log --oneline --all -S "problematic_function" > /tmp/history.txt &
wait
# Synthesize findings
gemini -m pro -o text -e "" "Synthesize these diagnostic findings:
Codebase:
\$(cat /tmp/codebase.txt)
GitHub Issues:
\$(cat /tmp/github.txt)
Git History:
\$(cat /tmp/history.txt)
Provide unified diagnosis with:
1. Most likely root cause
2. Confidence level
3. Key evidence
4. Differential diagnosis
5. Recommended action"
Root Cause Protocol
Always follow this hierarchy:
- INVESTIGATE - Search for evidence first
- UNDERSTAND - Read relevant code
- REASON - Apply systematic thinking
- FIX - Only then propose changes
Forbidden Shortcuts
| Symptom | BANNED Fix | REQUIRED Fix |
|---|---|---|
| Null error | if (x) { x.y } |
Find why x is null |
| Timeout | Increase timeout | Find what's slow |
| Flaky test | Skip test | Find race condition |
| Type error | as any |
Fix type hierarchy |
Investigation Commands
Codebase Search
# Find error patterns
rg "throw.*Error" --type ts -A 3
# Find function definitions
rg "function functionName|const functionName" --type ts
# Find usages
rg "functionName\(" --type ts
# Find recent changes
git log --oneline -20 --all -- src/problematic/
git diff HEAD~5 -- src/problematic/
GitHub Issue Search
# Search issues
gh search issues "error message" --repo owner/repo --state all
# View issue details
gh issue view 123 --repo owner/repo --comments
# Search across multiple repos
for repo in repo1 repo2 repo3; do
gh search issues "error" --repo owner/$repo --limit 5
done
Log Analysis
# Find logs first
find . -name "*.log" -type f
# Tail recent logs
tail -100 logs/app.log | grep -i error
# Search logs for patterns
grep -n "ERROR\|WARN" logs/*.log | tail -50
Framework-Based Reasoning
First Principles
gemini -m pro -o text -e "" "Apply first principles to this bug:
Problem: [description]
Questions:
1. What is this code supposed to do?
2. What is it actually doing?
3. What assumptions are being made?
4. Which assumption is wrong?"
Systematic Analysis
gemini -m pro -o text -e "" "Systematically analyze:
Problem: [description]
Walk through:
1. Input → What data enters?
2. Processing → What transformations?
3. State → What state changes?
4. Output → What comes out?
5. Where does expected diverge from actual?"
Critical Thinking
gemini -m pro -o text -e "" "Challenge assumptions:
Problem: [description]
For each potential cause:
- What evidence supports it?
- What evidence contradicts it?
- What would we expect to see if true?
- Can we rule it out?"
Output Format
A debug session should produce:
## ROOT CAUSE
Single sentence identifying the actual cause.
## CONFIDENCE
high | medium | low
## FIX
Specific code changes:
- File: src/file.ts
- Line: 42
- Before: `oldCode()`
- After: `newCode()`
## VERIFICATION
How to verify the fix works:
1. Run test: `npm test -- specific.test.ts`
2. Manual check: [steps]
## PREVENTION
How to prevent this in the future:
- Add validation at boundary
- Add regression test
Best Practices
- Logs first - Read logs before reading code
- Evidence required - No fix without citing specific evidence
- One cause - Find THE root cause, not symptoms
- Verify hypothesis - Test your theory before fixing
- Prevent recurrence - Add tests for the failure mode
- Document findings - Capture what you learned
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
testgen
Generate tests using AI and run test suites. Use for generating unit tests, running coverage reports, and mutation testing.
article
Generate technical articles and documentation using AI. Use for writing blog posts, documentation, and technical content.
packx
Bundle code context for AI. ALWAYS use --limit 49k unless user explicitly requests otherwise. Use for creating shareable code bundles and preparing context for LLMs.
long-agent
Manage long-running agent sessions. Use for tracking progress in extended tasks, maintaining context across long sessions, and managing multi-step workflows.
db
Database operations for SQLite, PostgreSQL, and MySQL. Use for queries, schema inspection, migrations, and AI-assisted query generation.
investigate
Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.
Didn't find tool you were looking for?