MCPInstall

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
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads debug automatically when relevant.

  3. 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:

  1. INVESTIGATE - Search for evidence first
  2. UNDERSTAND - Read relevant code
  3. REASON - Apply systematic thinking
  4. FIX - Only then propose changes

Forbidden Shortcuts

SymptomBANNED FixREQUIRED Fix
Null errorif (x) { x.y }Find why x is null
TimeoutIncrease timeoutFind what's slow
Flaky testSkip testFind race condition
Type erroras anyFix 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

  1. Logs first - Read logs before reading code
  2. Evidence required - No fix without citing specific evidence
  3. One cause - Find THE root cause, not symptoms
  4. Verify hypothesis - Test your theory before fixing
  5. Prevent recurrence - Add tests for the failure mode
  6. 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

View all →

gemini-image

johnlindquist/claude

Analyze images using Gemini's vision capabilities. Use for image analysis, text extraction from screenshots, and visual content understanding.

Media & Creative1.2K installs

memory

johnlindquist/claude

Open the skill to read its SKILL.md instructions.

362 installs

raycast-extension

johnlindquist/claude

Open the skill to read its SKILL.md instructions.

321 installs

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.

Docs & Writing269 installs

think

johnlindquist/claude

Open the skill to read its SKILL.md instructions.

258 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

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.