What makes the Root Cause Debugger different from standard debugging?

It enforces a strict 'Root Cause Protocol' that prevents shallow fixes like 'as any' or arbitrary timeouts, forcing a deep investigation into why the error occurs.

What external tools are required for this skill?

This skill requires the Gemini CLI (google-generativeai) for AI analysis and the GitHub CLI (gh) for searching repository issues and metadata.

How does the reasoning phase work?

It applies systematic thinking frameworks—such as First Principles and Critical Thinking—via AI to challenge assumptions and verify if the evidence supports the hypothesis.

Can it handle complex bugs involving multiple files?

Yes, it includes specific workflows for parallel investigation of codebase search results, git history, and log files to synthesize a unified diagnosis.

Does it provide the actual code for the fix?

Yes, every successful session produces a specific code fix with before/after blocks, the specific file and line numbers, and clear verification steps.

Root Cause Debugger

Name: Root Cause Debugger
Author: johnlindquist

byjohnlindquist

•

Security & Testing

Enforces a rigorous investigation-to-fix protocol that eliminates symptoms and solves underlying code issues using AI reasoning.

The Debug skill transforms the debugging process into a systematic, evidence-driven workflow that prioritizes finding the absolute root cause of software issues. By integrating codebase searches, GitHub issue tracking, and advanced AI reasoning via Gemini, it guides users through a disciplined 'Investigate → Understand → Reason → Fix' loop. This skill specifically forbids common developer shortcuts—such as arbitrary type casting or simply increasing timeouts—ensuring that every proposed solution is backed by data, includes clear verification steps, and addresses the fundamental logic failure.

Key Features

012 GitHub stars

02AI-powered reasoning frameworks including First Principles and Systematic Analysis

03Comprehensive diagnostic synthesis from codebase patterns, git history, and logs

04Standardized output format with confidence levels and regression prevention strategies

05Multi-phase investigation protocol: Investigate, Understand, Reason, and Fix

06Deep integration with GitHub CLI for identifying known issues and community workarounds

Use Cases

01Synthesizing external GitHub issues with local code context to solve framework-specific bugs

02Diagnosing intermittent race conditions or flaky test failures in complex repositories

03Enforcing high-quality debugging standards across a team to prevent 'band-aid' code fixes

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add johnlindquist/claude debug

For use in Claude.ai and ChatGPT

Download Skill