
debug
Unified debugging workflow enforcing root cause protocol. Investigate → Understand → Reason → Fix. Use when debugging bugs, errors, or unexpected behavior.
- Installs
- 55
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/johnlindquist/claude --skill debug- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads debug automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
FAQ
What does the debug skill do?
Unified debugging workflow enforcing root cause protocol. Investigate → Understand → Reason → Fix. Use when debugging bugs, errors, or unexpected behavior.
How do I install debug?
Run npx skills add https://github.com/johnlindquist/claude --skill debug in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debug/ (personal) or .claude/skills/debug/ (project).
Which AI agents can use debug?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is debug safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains debug?
It is published by johnlindquist in johnlindquist/claude. It has 55 recorded installs.
More from johnlindquist/claude
gemini-image
johnlindquist/claude
Analyze images using Gemini's vision capabilities. Use for image analysis, text extraction from screenshots, and visual content understanding.
brainstorm
johnlindquist/claude
Open the skill to read its SKILL.md instructions.
deepwiki
johnlindquist/claude
Query DeepWiki for repository documentation and structure. Use to understand open source projects, find API docs, and explore codebases.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.