---
name: troubleshoot
description: Diagnose and resolve issues in code, builds, and deployments
---

# /troubleshoot - Issue Diagnosis and Resolution

Systematic debugging and issue resolution for code, builds, and deployments.

## When to Use

- Code defects and runtime error investigation
- Build failure analysis and resolution
- Performance issue diagnosis
- Deployment problem analysis

## Usage

```
/skill troubleshoot [issue] [--type bug|build|performance|deployment] [--fix]
```

## Workflow

### 1. Analyze
- Examine issue description
- Gather relevant system state
- Collect error messages and logs

### 2. Investigate
- Identify potential root causes
- Form hypotheses based on evidence
- Prioritize investigation paths

### 3. Debug
- Execute structured debugging procedures
- Examine logs and state
- Test hypotheses systematically

### 4. Propose
- Validate solution approaches
- Assess impact and risks
- Present options if multiple exist

### 5. Resolve
- Apply appropriate fixes (if --fix)
- Verify resolution effectiveness
- Document the solution

## Issue Types

### Bug
- Error analysis and stack trace examination
- Code inspection and logic verification
- Regression identification
- Fix validation

### Build
- Build log analysis
- Dependency checking
- Configuration validation
- Environment verification

### Performance
- Metrics analysis
- Bottleneck identification
- Resource utilization review
- Optimization recommendations

### Deployment
- Environment analysis
- Configuration verification
- Service validation
- Connectivity checking

## Debugging Methodology

### 1. Reproduce
- Can you trigger the issue consistently?
- What are the exact steps?

### 2. Isolate
- Which component is failing?
- What changed recently?

### 3. Identify
- What is the root cause?
- Is this a symptom or the actual problem?

### 4. Fix
- What's the minimal fix?
- Are there side effects?

### 5. Verify
- Does the fix work?
- Are there related issues?

## Output Format

```markdown
# Troubleshooting Report

## Issue Summary
[Brief description of the problem]

## Root Cause Analysis
[Identified cause with evidence]

## Investigation Steps
1. [What was checked]
2. [What was found]
3. [How root cause was identified]

## Solution
[Recommended or applied fix]

## Verification
[How to verify the fix works]

## Prevention
[How to prevent recurrence]
```

## Examples

```
/skill troubleshoot "Null pointer exception in user service" --type bug --fix
# Analyzes error, identifies root cause, applies fix

/skill troubleshoot "TypeScript compilation errors" --type build
# Analyzes build logs and provides resolution steps

/skill troubleshoot "API response times degraded" --type performance
# Identifies performance bottlenecks with recommendations

/skill troubleshoot "Service not starting in production" --type deployment
# Checks environment, config, and dependencies
```

## Boundaries

**Will:**
- Execute systematic issue diagnosis
- Provide validated solutions
- Apply safe fixes with verification

**Will Not:**
- Apply risky fixes without confirmation
- Modify production without explicit permission
- Make architectural changes without analysis
