skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
johnlindquist/claude56 installs

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 debug
view source ↗

Is 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:

  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

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>