troubleshooting

# Troubleshooting

Diagnose and resolve common problems that arise during spec-driven development and feature implementation.

## When to Use This Skill

Use troubleshooting strategies when:
- Implementation doesn't match spec expectations
- Tasks are blocked by dependencies
- Requirements are unclear during coding
- Tests are failing or hard to write
- Performance doesn't meet requirements
- Integration problems occur

## Issue 1: Spec and Reality Diverge

### Symptoms
- Code structure doesn't match spec assumptions
- APIs are unavailable or deprecated
- Performance differs from expectations
- Integration points work differently than specified

### Resolution

**Immediate Actions:**
1. Document the gap exactly
2. Assess impact (minor detail vs fundamental issue)
3. Stop implementing until you understand implications

**Resolution Options:**

**Option 1: Update Spec (Minor Deviations)**
```
If difference is minor and doesn't affect requirements:
1. Update design section with actual approach
2. Adjust affected tasks
3. Document why change was needed
4. Continue implementation
```

**Option 2: Redesign (Major Deviations)**
```
If core assumptions are wrong:
1. Return to design phase
2. Incorporate new understanding
3. Re-validate against requirements
4. Create new task breakdown
5. Restart with corrected plan
```

**Option 3: Adjust Requirements (Fundamental Issues)**
```
If requirements can't be met as stated:
1. Document why requirements aren't achievable
2. Propose alternative approach
3. Get stakeholder approval
4. Update entire spec
5. Restart process
```

### Prevention
- Validate assumptions with code exploration during design
- Prototype risky integrations before finalizing spec
- Include technical spikes in task breakdown

## Issue 2: Task Dependencies Block Progress

### Symptoms
- Can't complete task without later features
- Multiple tasks need same file changes
- Tests need features not yet built
- Circular dependencies between tasks

### Resolution

**Str