error-troubleshooter

# Error Troubleshooter

## Overview

This skill enables systematic troubleshooting of unexpected behavior and technical failures - whether explicit errors or silent anomalies where commands succeed but don't produce expected results. Proactively investigate any mismatch between expected and actual outcomes using a structured approach that balances quick fixes with thorough analysis.

## When to Use This Skill

Trigger this skill automatically when encountering either:

### (1) Unexpected Behavior (Priority)
- **Command succeeded but expected effect didn't happen** - e.g., configuration set but not taking effect, file created but empty
- **Missing expected errors** - e.g., test was designed to fail but passed, validation that should reject but accepted
- **Wrong or unexpected output** - e.g., different data than expected, incorrect format, unexpected side effects
- **Silent failures** - no error reported but operation clearly didn't work
- **Behavioral anomalies** - program runs but behaves differently than intended

### (2) Explicit Failures
- **Error messages from SDK/API calls** - exceptions, error codes, failure responses
- **Tool execution failures** - Bash errors, script crashes, MCP tool failures
- **Runtime errors** - exceptions in any programming language
- **Build or compilation failures** - compiler errors, linking failures
- **System errors** - permission denied, file not found, connection refused

**Key principle**: If there's any mismatch between expected and actual behavior - whether explicit error or silent anomaly - this skill applies.

## Troubleshooting Decision Tree

### 1. Initial Assessment

When unexpected behavior or an error occurs, immediately assess the situation:

```
Unexpected Behavior or Error Detected
    ↓
What type of issue is this?
    │
    ├─ UNEXPECTED BEHAVIOR (command succeeded but wrong result)
    │   ↓
    │   Document the mismatch:
    │   - What was expected?
    │   - What actually happened?
    │   - Any error messages?