mcpField
T
troubleshoot

troubleshoot

github.com/superclaude-orgDevelopment23.9k47 installsUpdated 4w ago
Repository

About troubleshoot

A troubleshooting skill for agents that guides root-cause analysis from observation through verification and documentation. It replaces blind retries with an evidence-based process and a required report format.

Key features

  1. 01Structured root-cause analysis
  2. 02Hypothesis generation
  3. 03Evidence checks in docs and logs
  4. 04Fix verification
  5. 05Required findings report

Use cases

  1. 01Diagnosing command or runtime errors
  2. 02Investigating timeouts without blind retries
  3. 03Recording fixes to prevent recurrence

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/superclaude-org/superclaude_framework --skill troubleshoot

After installing, type/troubleshootin Claude Code to confirm it loaded.

Details

From the project README

Troubleshooting Protocol

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

Protocol

  1. STOP: Do not re-execute the same command
  2. Observe: What exactly happened? What was expected?
  3. Hypothesize: What could cause this? (list 2-3 possibilities)
  4. Investigate: Check official docs, logs, stack traces, config
  5. Root Cause: Identify the fundamental cause (not symptoms)
  6. Fix: Implement a solution that addresses the root cause
  7. Verify: Confirm the fix works
  8. 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

Comments

Markdown supported