/troubleshoot

name: troubleshoot
description: Systematic troubleshooting mode - Debug problems methodically with ask-for-help mechanism to prevent spinning wheels
version: 1.0.0
argument-hint: "[error-description-or-empty-for-interactive]"

Troubleshoot Command - Systematic Debugging Workflow

You are in **SYSTEMATIC TROUBLESHOOTING MODE** - a methodical 5-stage process designed to diagnose and fix problems efficiently while preventing endless debugging cycles.

⚠️ **CRITICAL PRINCIPLES**:

• **ASK FOR HELP** after 3 failed attempts or when encountering complex issues
• **ONE CHANGE AT A TIME** - never make multiple changes simultaneously
• **GATHER BEFORE GUESSING** - always collect full context before attempting fixes
• **DOCUMENT EVERYTHING** - record all attempts in TROUBLESHOOT.md
• **NO SPINNING WHEELS** - if stuck, stop and ask for user guidance

Initial Input

$ARGUMENTS

If error description provided, use it as starting point. Otherwise, ask: "What problem are you encountering? Please describe the error or unexpected behavior."

🎯 Troubleshooting Objectives

1. **Understand the Problem** - Gather complete context 2. **Classify the Issue** - Determine complexity and type 3. **Form Hypotheses** - Generate specific, testable theories 4. **Test Methodically** - Validate one hypothesis at a time 5. **Document Solution** - Record the fix and lessons learned

Troubleshooting Workflow

Stage 1: Context Gathering (2-5 min)

**DO NOT SKIP THIS STAGE** - Rushing to fix without context leads to wasted time.

Information to Collect

1. **Full Error Message**

• Never skim - read the complete error message
• Note exact error text, error codes, line numbers
• Capture full stack trace if available

2. **When Did This Start?**

• What changed recently? (git diff, git log -5)
• New code, dependencies, config changes?
• Environment changes? (OS update, new package versions)

3. **Consistency Check**

• Does it happen every time or intermittently?
• Specific conditions that trigger it?
• Works in different environment? (local vs production, different machine)

4. **What's Been Tried?**

• Ask user: "What have you already attempted?"
• Avoid repeating failed attempts

5. **System State**

• Check configuration files
• Verify environment variables
• Review recent commits (git log -10 --oneline)
• Check dependency versions (package.json, requirements.txt, go.mod)
• Review logs for related errors

Context Gathering Checklist

Before moving to Stage 2, confirm:

### Context Gathered
- [ ] Full error message captured (exact text)
- [ ] Stack trace analyzed (if available)
- [ ] Recent changes reviewed (git diff, git log)
- [ ] Configuration files checked
- [ ] Dependencies verified (versions, missing packages)
- [ ] Environment variables validated
- [ ] Logs reviewed for related errors
- [ ] Reproduction steps documented

Document in TROUBLESHOOT.md

# Troubleshooting Session: [Date/Time]

## Problem Description
[User's description of the issue]

## Error Message

[Exact error text with full stack trace]

## Context
- **When Started**: [Timeline]
- **Consistency**: [Always/Sometimes - conditions]
- **Recent Changes**: [List from git log]
- **Environment**: [OS, versions, etc.]
- **Previous Attempts**: [What user tried]

## System State
- **Config Files**: [Status]
- **Dependencies**: [Versions]
- **Environment Variables**: [Status]

Stage 2: Problem Classification (1-2 min)

Classify the issue to determine approach and complexity.

Error Categories

🔤 Syntax Error

**Indicators**: Missing punctuation, typo, incorrect syntax **Complexity**: Simple **Fix Time**: < 5 min **Approach**: Quick fix, no ask-for-help needed

**Examples**:

• Missing semicolon, bracket, parenthesis
• Typo in variable/function name
• Incorrect indentation (Python)
• Missing import statement

🧮 Logic Error

**Indicators**: Code runs but produces wrong results **Complexity**: Medium **Fix Time**: 15-30 min **Approach**: Systematic debugging, ask-for-help if > 3 attempts

**Examples**:

• Off-by-one errors in loops
• Wrong comparison operator (< vs <=)
• Incorrect algorithm implementation
• Wrong business logic

⚡ Runtime Error

**Indicators**: Code crashes during execution **Complexity**: Medium **Fix Time**: 10-20 min **Approach**: Check inputs, boundaries, async operations

**Examples**:

• Null/undefined reference
• Type mismatch (string vs number)
• Array out of bounds
• Promise rejection
• File not found

🐌 Performance Issue

**Indicators**: Slow execution, high resource usage **Complexity**: High **Fix Time**: 30-60 min **Approach**: Profiling required, ask-for-help early

**Examples**:

• N+1 database queries
• Memory leak
• Inefficient algorithm (O(n²) instead of O(n))
• Missing database indexes
• Unoptimized images/assets

⚙️ Configuration Issue

**Indicators**: Missing settings, wrong environment **Complexity**: Simple to Medium **Fix Time**: 5-15 min **Approach**: Check configs, env vars, permissions

**Examples**:

• Wrong environment variable
• Missing dependency
• Incorrect file permissions
• Port already in use
• Wrong API endpoint

🔐 Security Issue

**Indicators**: Vulnerable dependencies, exposed secrets **Complexity**: High **Fix Time**: 30+ min **Approach**: Ask-for-help immediately (critical)

**Examples**:

• Exposed API keys
• SQL injection vulnerability
• XSS vulnerability
• Insecure authentication
• Outdated vulnerable package

🌐 Network/Integration Issue

**Indicators**: API failures, timeout errors, connectivity **Complexity**: Medium to High **Fix Time**: 20-40 min **Approach**: Check endpoints, auth, network

**Examples**:

• API endpoint changed
• Authentication token expired
• CORS errors
• Network timeout
• Rate limiting

🏗️ Architectural Issue

**Indicators**: Race conditions, concurrency issues, design flaws **Complexity**: Very High **Fix Time**: Hour