New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Root Cause Debugging

by garrytan in garrytan/gstack

Investigates bugs, errors and stack traces in phases and requires a root-cause hypothesis to be confirmed before any fix is written.

MITAuto-check passedDevelopment

Install Root Cause Debugging

skills CLI
$ npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install garrytan/gstack gstack-openclaw-investigate --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/garrytan/gstack.git skills-src && mkdir -p .claude/skills && cp -r skills-src/openclaw/skills/gstack-openclaw-investigate .claude/skills/gstack-openclaw-investigate && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
gstack-openclaw-investigate
GitHub stars
136k
Token cost
~1.4k tokens
SKILL.md length
751 words
Files
1
Skills in repo
56
Repo updated
First seen
Licence
MIT

At a glance

Investigates bugs, errors and stack traces in phases and requires a root-cause hypothesis to be confirmed before any fix is written.

  • Works in 5 steps: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → …
  • A user reports an error, a stack trace or something that stopped working
  • SKILL.md covers Iron Law, Phase 1: Root Cause…, Phase 2: Pattern Analysis and Phase 3: Hypothesis Testing, plus 3 more sections
  • Calls git

What it does

The skill's one rule is that no fix comes before a root cause investigation. Phase one gathers context: reading error messages, stack traces and reproduction steps, asking one question at a time when more detail is needed, tracing the code path from the symptom back to likely causes, checking recent changes with git log, reproducing the bug and looking for earlier debugging sessions in the same area. It ends with a stated, testable root cause hypothesis.

Phase two compares the failure with known patterns: race conditions, null propagation, state corruption, integration failures, configuration drift and stale caches. When nothing matches, the agent may search for the error type online after removing hostnames, IPs, file paths, SQL and customer data. Phase three tests the hypothesis before any fix is written.

When your agent uses it

  • A user reports an error, a stack trace or something that stopped working
  • Tracking down the cause of an intermittent or environment-specific failure
  • Investigating a regression that appeared after recent changes

Example prompts

  • “The nightly import job started failing after Tuesday's deploy. Find the root cause before changing anything.”
  • “Here is the stack trace from the checkout page. Why is it throwing a TypeError?”
  • “Login works locally but fails in staging. Investigate why.”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Root Cause Investigation
  2. Pattern Analysis
  3. Hypothesis Testing
  4. Implementation
  5. Verification & Report

What it can do on your machine

Read from SKILL.md and the folder at commit 20eb620. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Root Cause Debugging loads about 1.4k tokens when it runs. Until then it costs about 53 tokens; SKILL.md has 751 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~53
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from garrytan/gstack at commit 20eb620, republished under its MIT licence (© garrytan). 751 words, ~1,368 tokens.

Download SKILL.mdSave it as .claude/skills/gstack-openclaw-investigate/SKILL.md (or your agent's skills folder).
name
gstack-openclaw-investigate
description
Use when asked to debug, fix a bug, investigate an error, or do root cause analysis, and when users report errors, stack traces, unexpected behavior, or say something stopped working.

Systematic Debugging

Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find. Find the root cause, then fix it.

Phase 1: Root Cause Investigation

Gather context before forming any hypothesis.

  1. Collect symptoms: Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time. Don't ask five questions at once.

  2. Read the code: Trace the code path from the symptom back to potential causes. Search for all references, read the logic around the failure point.

  3. Check recent changes:

    bash
    git log --oneline -20 -- <affected-files>

    Was this working before? What changed? A regression means the root cause is in the diff.

  4. Reproduce: Can you trigger the bug deterministically? If not, gather more evidence before proceeding.

  5. Check memory for prior debugging sessions on the same area. Recurring bugs in the same files are an architectural smell.

Output: "Root cause hypothesis: ..." ... a specific, testable claim about what is wrong and why.

Phase 2: Pattern Analysis

Check if this bug matches a known pattern:

Race condition ... Intermittent, timing-dependent. Look at concurrent access to shared state.

Nil/null propagation ... NoMethodError, TypeError. Missing guards on optional values.

State corruption ... Inconsistent data, partial updates. Check transactions, callbacks, hooks.

Integration failure ... Timeout, unexpected response. External API calls, service boundaries.

Configuration drift ... Works locally, fails in staging/prod. Env vars, feature flags, DB state.

Stale cache ... Shows old data, fixes on cache clear. Redis, CDN, browser cache.

Also check:

  • Known issues in the project for related problems
  • Git log for prior fixes in the same area. Recurring bugs in the same files are an architectural smell, not a coincidence.

External search: If the bug doesn't match a known pattern, search for the error type online. Sanitize first: strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message.

Phase 3: Hypothesis Testing

Before writing ANY fix, verify your hypothesis.

  1. Confirm the hypothesis: Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match?

  2. If the hypothesis is wrong: Search for the error (sanitize sensitive data first). Return to Phase 1. Gather more evidence. Do not guess.

  3. 3-strike rule: If 3 hypotheses fail, STOP. Tell the user:

    "3 hypotheses tested, none match. This may be an architectural issue rather than a simple bug."

    Options:

    • Continue investigating with a new hypothesis (describe it)
    • Escalate for human review (needs someone who knows the system)
    • Add logging and wait (instrument the area and catch it next time)

Red flags ... if you see any of these, slow down:

  • "Quick fix for now" ... there is no "for now." Fix it right or escalate.
  • Proposing a fix before tracing data flow ... you're guessing.
  • Each fix reveals a new problem elsewhere ... wrong layer, not wrong code.
Show full SKILL.md (269 more words)Show less

Phase 4: Implementation

Once root cause is confirmed:

  1. Fix the root cause, not the symptom. The smallest change that eliminates the actual problem.

  2. Minimal diff: Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code.

  3. Write a regression test that:

    • Fails without the fix (proves the test is meaningful)
    • Passes with the fix (proves the fix works)

  4. Run the full test suite. No regressions allowed.

  5. If the fix touches >5 files: Flag the blast radius to the user before proceeding. That's large for a bug fix.

Phase 5: Verification & Report

Fresh verification: Reproduce the original bug scenario and confirm it's fixed. This is not optional.

Run the test suite.

Output a structured debug report:

DEBUG REPORT

  • Symptom: what the user observed
  • Root cause: what was actually wrong
  • Fix: what was changed, with file references
  • Evidence: test output, reproduction showing fix works
  • Regression test: location of the new test
  • Related: prior bugs in same area, architectural notes
  • Status: DONE | DONE_WITH_CONCERNS | BLOCKED

Save the report to memory/ with today's date so future sessions can reference it.

Important Rules

  • 3+ failed fix attempts: STOP and question the architecture. Wrong architecture, not failed hypothesis.
  • Never apply a fix you cannot verify. If you can't reproduce and confirm, don't ship it.
  • Never say "this should fix it." Verify and prove it. Run the tests.
  • If fix touches >5 files: Flag to user before proceeding.
  • Completion status:
    • DONE ... root cause found, fix applied, regression test written, all tests pass
    • DONE_WITH_CONCERNS ... fixed but cannot fully verify (e.g., intermittent bug, requires staging)
    • BLOCKED ... root cause unclear after investigation, escalated

© garrytan, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in openclaw/skills/gstack-openclaw-investigate of garrytan/gstack.

Open the folder on GitHubat commit 20eb620

Compare with similar skills

Root Cause Debugging next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Root Cause Debugging compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Root Cause Debugging this skillgarrytan/gstack136k—~1.4kAutomated safety check: PassMIT
OpenLogi macOS Permissions TriageAprilNEA/OpenLogi23k—~2.5kAutomated safety check: NotesApache-2.0
Bug Finder for daisyUIsaadeghi/daisyui43k—~2.3kAutomated safety check: PassMIT
Graph-Based Bug Tracingtirth8205/code-review-graph32k1 repos~287Automated safety check: PassMIT
Systematic DebuggingChrisWiles/claude-code-showcase6.1k3 repos~1.2kAutomated safety check: PassNone
Debugging and Error Recoveryaddyosmani/agent-skills103k1 repos~2.6kAutomated safety check: PassMIT

Similar skills

  • OpenLogi macOS Permissions Triage

    AprilNEA/OpenLogi

    Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated today
    DevelopmentAuto-check: notes

  • Bug Finder for daisyUI

    saadeghi/daisyui

    Investigates suspected bugs in the daisyUI monorepo through read-only analysis, then writes a decision-ready fix plan in tmp/bugs without changing any product code.

    43k GitHub stars~2.3k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Graph-Based Bug Tracing

    tirth8205/code-review-graph

    Traces a bug through a code knowledge graph, following callers, callees and execution flow before opening source files, within a small token budget.

    32k GitHub starsUsed in 1 repo~287 tokens
    DevelopmentAuto-check passed

  • Systematic Debugging

    ChrisWiles/claude-code-showcase

    Applies a four-phase debugging routine that finds the root cause of a bug or failing test before any fix is written.

    6.1k GitHub starsUsed in 3 repos~1.2k tokens
    DevelopmentAuto-check passed

  • Debugging and Error Recovery

    addyosmani/agent-skills

    Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.

    103k GitHub starsUsed in 1 repo~2.6k tokens
    DevelopmentAuto-check passed

  • Debugging Strategies

    sangrokjung/claude-forge

    Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack.

    852 GitHub starsUsed in 13 repos~3.1k tokens
    DevelopmentAuto-check passed

More from garrytan/gstack

All 56 skills in this repo

  • Gstack Skill Router

    garrytan/gstack

    Router for the gstack skill suite. (gstack)

    136k GitHub stars~4k tokensUpdated today
    Auto-check: notes

  • Weekly Engineering Retro

    garrytan/gstack

    Builds a weekly engineering retrospective from git history: commit counts, per-person contributions, work patterns and code quality numbers over a chosen window.

    136k GitHub stars~2.4k tokensUpdated today
    Auto-check passed

  • Aside Browser Driver

    garrytan/gstack

    Drives a real browser through Aside so the agent can open a page, read it, click through a flow, take screenshots and check console errors.

    136k GitHub stars~8.5k tokensUpdated today
    Auto-check: notes

  • Live-Device iOS QA

    garrytan/gstack

    Tests a SwiftUI app on a real iPhone connected by USB, reading the Swift source and then looping through screenshot, analysis and action to find bugs.

    136k GitHub stars~11k tokensUpdated today
    Auto-check: notes

  • Cross-Model Benchmark

    garrytan/gstack

    Sends one prompt to Claude, GPT through the Codex CLI and Gemini, then tabulates response time, token use and cost, with an optional judged quality score.

    136k GitHub stars~4k tokensUpdated today
    Auto-check: notes

  • CSO Security Audit

    garrytan/gstack

    Runs an evidence-first security audit of a codebase through gstack's trusted launcher, with static findings by default and isolated reproduction when enabled.

    136k GitHub stars~4.5k tokensUpdated today
    Auto-check passed

Categories

Questions about Root Cause Debugging

What does Root Cause Debugging do?

Investigates bugs, errors and stack traces in phases and requires a root-cause hypothesis to be confirmed before any fix is written. The skill's one rule is that no fix comes before a root cause investigation. Phase one gathers context: reading error messages, stack traces and reproduction steps, asking one question at a time when more detail is needed, tracing the code path from the symptom back to likely causes, checking recent changes with git log, reproducing the bug and looking for earlier debugging sessions in the same area.

When should I use Root Cause Debugging?

Root Cause Debugging fits situations like: A user reports an error, a stack trace or something that stopped working; tracking down the cause of an intermittent or environment-specific failure; investigating a regression that appeared after recent changes.

How do I install Root Cause Debugging in Claude Code?

Run `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a claude-code`. Or copy the skill folder (openclaw/skills/gstack-openclaw-investigate in garrytan/gstack) into .claude/skills/gstack-openclaw-investigate in your project. Claude Code loads it when a task matches its description.

How do I install Root Cause Debugging in Codex?

Run `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a codex`. Or copy the skill folder (openclaw/skills/gstack-openclaw-investigate in garrytan/gstack) into .agents/skills/gstack-openclaw-investigate in your project. Codex loads it when a task matches its description.

Can I use Root Cause Debugging in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/gstack-openclaw-investigate, .gemini/skills/gstack-openclaw-investigate, .github/skills/gstack-openclaw-investigate and .opencode/skills/gstack-openclaw-investigate in your project.

What does Root Cause Debugging need to run?

Going by SKILL.md and its folder, Root Cause Debugging needs the command-line tools its instructions call (git).

Does Root Cause Debugging access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Root Cause Debugging safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Root Cause Debugging use?

Root Cause Debugging is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Root Cause Debugging use?

About 1.4k tokens (SKILL.md is roughly 5.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Root Cause Debugging?

Skills that share tags, products or a category with Root Cause Debugging: OpenLogi macOS Permissions Triage (AprilNEA/OpenLogi, 23k stars), Bug Finder for daisyUI (saadeghi/daisyui, 43k stars), Graph-Based Bug Tracing (tirth8205/code-review-graph, 32k stars) and Systematic Debugging (ChrisWiles/claude-code-showcase, 6.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Root Cause Debugging?

garrytan (a GitHub user) maintains it in garrytan/gstack, which has 135,670 GitHub stars. The repository holds 56 skills in this directory. The repository was last updated on October 9, 2026.

Source: garrytan/gstack on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.