troubleshoot — Claude Code command: what it does, how to install
troubleshoot diagnoses runtime errors, build failures, performance bottlenecks, and deployment bugs. It inspects the system state and never modifies files unless passed --fix.
MIT ★ 23,950 updated 2026-09-27
.claude/commands/troubleshoot.mdWhat troubleshoot does
/sc:troubleshoot coordinates diagnostics across application code, build pipelines, system performance, and deployments. It examines runtime crashes, compilation failures, latency issues, and unresponsive services. For data collection, it relies on Read to inspect logs, Bash to run diagnostics, and Grep to track down error signatures.
The workflow follows five distinct phases: problem analysis, root-cause investigation via hypotheses, structured debugging, solution ranking, and resolution. The final output provides a structured report that explains the root cause alongside potential remedies and their associated risks.
By default, the command strictly runs in diagnosis-first mode. Without the --fix flag, it makes zero file changes and halts after presenting its findings. Even when invoked with --fix, it requires explicit user approval before touching code and runs tests to verify the outcome.
What it helps with
- trace runtime exceptions down to root causes
- investigate build logs and configuration errors
- detect bottlenecks causing API latency spikes
- debug deployment failures when services fail to start
Example prompts for the agent
- /sc:troubleshoot "Null pointer exception in user service" --type bug --trace
- /sc:troubleshoot "TypeScript compilation errors" --type build --fix
- /sc:troubleshoot "API response times degraded" --type performance
How to install troubleshoot
Manually: put the files in place
.claude/commands/troubleshoot.mdCall it with /troubleshoot. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/troubleshoot.mdCall it with /prompts:troubleshoot. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/troubleshoot.prompt.mdManually: put the files in place
.gemini/commands/troubleshoot.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about troubleshoot
How do I install troubleshoot in Claude Code?
Add the command definition to your project at .claude/commands/troubleshoot.md. Claude Code will immediately register /sc:troubleshoot.
What does the troubleshoot command do?
It investigates code exceptions, build errors, and runtime failures using Read, Bash, and Grep. It then outputs a diagnostic report with root causes and ranked solutions.
Will troubleshoot modify files automatically?
No, it operates in diagnosis-only mode by default and makes no edits without --fix. If --fix is passed, it still asks for confirmation before changing code and verifies fixes with tests.
Source text
troubleshoot.md · MIT
--- name: troubleshoot description: "Diagnose and resolve issues in code, builds, deployments, and system behavior" category: utility complexity: basic mcp-servers: [] personas: [] --- # /sc:troubleshoot - Issue Diagnosis and Resolution ## Triggers - Code defects and runtime error investigation requests - Build failure analysis and resolution needs - Performance issue diagnosis and optimization requirements - Deployment problem analysis and system behavior debugging ## Usage ``` /sc:troubleshoot [issue] [--type bug|build|performance|deployment] [--trace] [--fix] ``` ## Behavioral Flow 1. **Analyze**: Examine issue description and gather relevant system state information 2. **Investigate**: Identify potential root causes through systematic pattern analysis 3. **Debug**: Execute structured debugging procedures including log and state examination 4. **Propose**: Validate solution approaches with impact assessment and risk evaluation 5. **Resolve**: Apply appropriate fixes and verify resolution effectiveness Key behaviors: - Systematic root cause analysis with hypothesis testing and evidence collection - Multi-domain troubleshooting (code, build, performance, deployment) - Structured debugging methodologies with comprehensive problem analysis - Safe fix application with verification and documentation ## Tool Coordination - **Read**: Log analysis and system state examination - **Bash**: Diagnostic command execution and system investigation - **Grep**: Error pattern detection and log analysis - **Write**: Diagnostic reports and resolution documentation ## Key Patterns - **Bug Investigation**: Error analysis → stack trace examination → code inspection → fix validation - **Build Troubleshooting**: Build log analysis → dependency checking → configuration validation - **Performance Diagnosis**: Metrics analysis → bottleneck identification → optimization recommendations - **Deployment Issues**: Environment analysis → configuration verification → service validation ## Examples ### Code Bug Investigation ``` /sc:troubleshoot "Null pointer exception in user service" --type bug --trace # Systematic analysis of error context and stack traces # Identifies root cause and provides targeted fix recommendations ``` ### Build Failure Analysis ``` /sc:troubleshoot "TypeScript compilation errors" --type build --fix # Analyzes build logs and TypeScript configuration # Automatically applies safe fixes for common compilation issues ``` ### Performance Issue Diagnosis ``` /sc:troubleshoot "API response times degraded" --type performance # Performance metrics analysis and bottleneck identification # Provides optimization recommendations and monitoring guidance ``` ### Deployment Problem Resolution ``` /sc:troubleshoot "Service not starting in production" --type deployment --trace # Environment and configuration analysis # Systematic verification of deployment requirements and dependencies ``` ## Boundaries **Will:** - Execute systematic issue diagnosis using structured debugging methodologies - Provide validated solution approaches with comprehensive problem analysis - Apply safe fixes with verification and detailed resolution documentation **Will Not:** - Apply risky fixes without proper analysis and user confirmation - Modify production systems without explicit permission and safety validation - Make architectural changes without understanding full system impact ## CRITICAL BOUNDARIES **DIAGNOSE FIRST - FIXES REQUIRE `--fix` FLAG** This command is DIAGNOSIS-FIRST by default. **Default behavior (no `--fix` flag)**: - Diagnose the issue - Identify root cause - Propose solution options - **STOP and present findings to user** - do not apply any fixes **With `--fix` flag**: - After diagnosis, prompt user for confirmation before applying - Apply fix only after user explicitly approves - Verify fix with tests **Explicitly Will NOT** (without `--fix` flag): - Apply any code changes - Modify any files - Execute fixes automatically **Output**: Diagnostic report containing: - Issue description - Root cause analysis - Proposed solutions (ranked) - Risk assessment for each solution **Next Step**: User reviews diagnosis, then either: - Re-run with `--fix` flag to apply recommended fix - Use `/sc:improve` for broader refactoring
© SuperClaude-Org · MIT · SuperClaude-Org/SuperClaude_Framework