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 data

For Slow Tests:

• Use test doubles for expensive operations
• Parallelize test execution
• Optimize database setup/teardown
• Cache expensive setups

Prevention

• Design for testability during design phase
• Include test strategy in design document
• Write tests alongside implementation

Issue 6: Performance Problems

Symptoms

• Slow response times
• High memory usage
• Database query issues
• Excessive network calls

Resolution

Step 1: Measure

• Profile the code
• Identify bottlenecks
• Quantify the gap
• Establish baseline

Step 2: Analyze

• Algorithmic complexity?
• Database inefficiency?
• Network latency?
• Resource contention?

Step 3: Optimize

• Target biggest bottleneck first
• Make one change at a time
• Measure after each change
• Document optimizations

Step 4: Validate

• Verify requirements met
• Check no regressions
• Add performance tests
• Document characteristics

Common Fixes:

• Database: Add indexes, optimize queries, implement caching
• Algorithm: Better data structures, reduce complexity, lazy loading
• Network: Batch requests, compression, reduce payload size

Prevention

• Include performance requirements in spec
• Design with performance in mind
• Profile early and often

Issue 7: Integration Problems

Symptoms

• Works locally, fails in integration
• Timing issues in production
• Data format mismatches
• Auth failures

Resolution

Step 1: Isolate Problem

• Does it work in isolation?
• Which integration point fails?
• Consistent or intermittent?
• What's different in integration environment?

Step 2: Verify Contracts

• Check API specifications
• Validate data formats
• Verify authentication flow
• Review error responses

Step 3: Test Integration Points

• Test each integration separately
• Use integration test environment
• Verify error handling
• Check timeout behavior

Step 4: Fix and Validate

• Implement fix
• Add integration tests
• Verify in integration environment
• Update spec if assumptions wrong

Common Issues:

• Configuration differences (URLs, credentials)
• Data format issues (dates, encoding, nulls)
• Timing issues (race conditions, timeouts)

Prevention

• Test in integration environment early
• Document integration requirements clearly
• Include integration tests in task breakdown

Issue 8: Scope Creep During Implementation

Symptoms

• "While I'm here, I should also..."
• "It would be easy to add..."
• Tasks taking longer than estimated
• Feature complexity growing

Resolution

Step 1: Recognize It

• Notice when going beyond spec
• Identify additions vs requirements
• Assess if it's scope creep

Step 2: Evaluate

• Is it required for current requirements?
• Is it a bug fix or enhancement?
• Cost of doing now vs later?

Step 3: Decide

Option A: Required for Current Feature

• Update spec with new requirement
• Add to current work
• Adjust timeline

Option B: Nice to Have

• Document as future enhancement
• Complete current spec first
• Create separate spec later

Option C: Out of Scope

• Note as explicitly excluded
• Create future spec if valuable
• Stay focused on current work

Red Flags

• "Just one more feature"
• "While we're changing this..."
• Refactoring beyond what's needed
• Gold-plating solutions

Prevention

• Clear requirements and acceptance criteria
• Regular review against spec
• Time-box implementation tasks

Debugging Strategies

Rubber Duck Debugging

Explain the problem out loud. Often the explanation reveals the solution.

Binary Search

Isolate by dividing code in half repeatedly until you find the issue.

Strategic Logging

Add logging to understand code flow and data transformations.

Minimal Reproduction

Create smallest test case that reproduces the issue.

Compare Working vs Broken

Find similar working code and compare differences.

When to Update the Spec

Always Update When:

• Design assumptions were wrong
• Requirements need clarification
• Tasks need reordering
• New edge cases discovered
• Technical approach changes

Document:

• Why changes were made
• When they were made
• Impact on timeline
• Alternatives considered

Getting Unstuck

When truly blocked:

1. Take a break - Solution often comes when you step away
2. Review the spec - Re-read requirements and design
3. Ask for help - Get a second pair of eyes
4. Simplify - Solve a simpler version first
5. Prototype - Try multiple approaches quickly
6. Go back a phase - Maybe the spec needs work