Agent Skills › SuperClaude-Org/SuperClaude_Framework › troubleshoot

troubleshoot

GitHub

提供系统化的根因分析排查协议，指导AI在遇到错误、Bug或异常行为时，遵循停止重试、观察现象、假设验证等步骤定位根本原因并修复，严禁盲目重试或忽略警告。

plugins/superclaude/skills/troubleshoot/SKILL.md SuperClaude-Org/SuperClaude_Framework

Trigger Scenarios

用户报告程序报错或异常需要诊断Bug或意外行为的原因

Install

npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -g -y

More Options

Non-standard path

npx skills add https://github.com/SuperClaude-Org/SuperClaude_Framework/tree/master/plugins/superclaude/skills/troubleshoot -g -y

Use without installing

npx skills use SuperClaude-Org/SuperClaude_Framework@troubleshoot

指定 Agent (Claude Code)

npx skills add SuperClaude-Org/SuperClaude_Framework --skill troubleshoot -a claude-code -g -y

安装 repo 全部 skill

npx skills add SuperClaude-Org/SuperClaude_Framework --all -g -y

预览 repo 内 skill

npx skills add SuperClaude-Org/SuperClaude_Framework --list

SKILL.md

Frontmatter

{
    "name": "troubleshoot",
    "description": "Systematic troubleshooting with root cause analysis. Use when users report errors, bugs, or unexpected behavior. Never retry without understanding why."
}

Troubleshooting Protocol

Follow this systematic root cause analysis process. NEVER retry the same approach without understanding WHY it failed.

Protocol

STOP: Do not re-execute the same command
Observe: What exactly happened? What was expected?
Hypothesize: What could cause this? (list 2-3 possibilities)
Investigate: Check official docs, logs, stack traces, config
Root Cause: Identify the fundamental cause (not symptoms)
Fix: Implement a solution that addresses the root cause
Verify: Confirm the fix works
Learn: Document the solution for future reference

Anti-Patterns (strictly prohibited)

"Got an error. Let's just try again"
"Retry: attempt 1... attempt 2... attempt 3..."
"It timed out, so let's increase the wait time" (ignoring root cause)
"There are warnings but it works, so it's fine" (future technical debt)

Required Format

## Root Cause Analysis

**Error**: [Exact error message]
**Expected**: [What should have happened]
**Cause**: [Root cause with evidence]
**Fix**: [Solution addressing root cause]
**Prevention**: [How to prevent recurrence]

Apply this to: $ARGUMENTS