/troubleshooting

name: troubleshooting
description: Diagnose and resolve common issues during spec-driven development and implementation. Learn strategies for handling spec-reality divergence, dependency blocks, unclear requirements, and other execution challenges.
license: MIT
compatibility: Claude Code, Cursor, VS Code, Windsurf
metadata:
  category: methodology
  complexity: intermediate
  author: Kiro Team
  version: "1.0.0"

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

**Strategy 1: Reorder Tasks**

If dependency was missed in planning:
1. Identify the prerequisite task
2. Complete it first
3. Return to blocked task
4. Update task sequence for future

**Strategy 2: Split Tasks**

If task is too large:
1. Break blocked task into smaller pieces
2. Complete parts that aren't blocked
3. Queue dependent parts for later
4. Update task breakdown

**Strategy 3: Use Mocking/Stubbing**

If dependency is complex:
1. Create minimal stub/mock of dependency
2. Complete current task against stub
3. Replace stub when real dependency ready
4. Add integration testing task

**Strategy 4: Parallel Development**

If dependency is in progress:
1. Define clear interface/contract
2. Implement against interface
3. Test with mock implementation
4. Integrate when dependency completes

Prevention

• Map dependencies explicitly during task planning
• Order tasks to minimize blocking
• Identify tasks that can be parallelized

Issue 3: Requirements Unclear During Implementation

Symptoms

• Multiple valid interpretations
• Edge cases not addressed
• Conflicting requirements discovered
• UX details missing

Resolution

**Step 1: Analyze the Ambiguity**

• What exactly is unclear?
• What are possible interpretations?
• What's the impact of each?
• Is this common or edge case?

**Step 2: Propose Solution**

• What's most consistent with existing requirements?
• What aligns with user needs?
• What's technically simplest?
• Make recommendation with rationale

**Step 3: Get Clarification**

• Update requirements with clarification
• Update acceptance criteria if needed
• Document decision rationale
• Proceed with implementation

**Step 4: Update Tasks**

• Adjust current task if needed
• Add new tasks if solution is complex
• Update testing tasks

Prevention

• Probe for edge cases during requirements phase
• Use examples to clarify requirements
• Review requirements with developers before design

Issue 4: Technical Debt Creates Friction

Symptoms

• Need to refactor before adding feature
• Tests are brittle or missing
• Code is tightly coupled
• No clear extension points

Resolution

**Strategy 1: Refactor-First**

If refactoring is bounded and low-risk:
1. Create refactoring tasks separate from feature
2. Get approval for additional work
3. Complete refactoring with tests
4. Proceed with feature

**Strategy 2: Parallel Track**

If refactoring is extensive:
1. Implement feature with workarounds
2. Create separate refactoring initiative
3. Document technical debt created
4. Plan future cleanup

**Strategy 3: Incremental Improvement**

If refactoring can be done in pieces:
1. Refactor only what you touch
2. Leave code better than you found it
3. Add tests for refactored areas
4. Continue feature implementation

Prevention

• Assess existing code quality during design
• Include refactoring tasks when needed
• Set realistic timelines accounting for debt

Issue 5: Tests Failing or Hard to Write

Symptoms

• Tests fail randomly (flaky)
• Setup code is complex
• Mocking is complicated
• Tests take too long

Resolution

**For Tightly Coupled Code:**

• Extract interfaces for dependencies
• Use dependency injection
• Create test fixtures/factories
• Implement test doubles

**For Complex Setup:**

• Create reusable test utilities
• Use test builders/factories
• Implement setup helpers
• Share fixtures across tests

**For Flaky Tests:**

• Remove timing dependencies
• Eliminate global state
• Mock external dependencies
• Use deterministic test da