debug
Unified debugging workflow enforcing root cause protocol. Investigate → Understand → Reason → Fix. Use when debugging bugs, errors, or unexpected behavior.
How do I install this agent skill?
npx skills add https://github.com/johnlindquist/claude --skill debugIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a structured debugging workflow using standard developer tools and the Google Gemini CLI. It is generally safe but contains an inherent risk of indirect prompt injection because it incorporates local code and log files directly into prompts sent to the AI without sanitization. It also involves sending codebase content to an external AI service for analysis.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/johnlindquist/claude/debug">View debug on skillZs</a>