// 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.
| 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"} |
Diagnose and resolve common problems that arise during spec-driven development and feature implementation.
Use troubleshooting strategies when:
Immediate Actions:
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
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
Step 1: Analyze the Ambiguity
Step 2: Propose Solution
Step 3: Get Clarification
Step 4: Update Tasks
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
For Tightly Coupled Code:
For Complex Setup:
For Flaky Tests:
For Slow Tests:
Step 1: Measure
Step 2: Analyze
Step 3: Optimize
Step 4: Validate
Common Fixes:
Step 1: Isolate Problem
Step 2: Verify Contracts
Step 3: Test Integration Points
Step 4: Fix and Validate
Common Issues:
Step 1: Recognize It
Step 2: Evaluate
Step 3: Decide
Option A: Required for Current Feature
Option B: Nice to Have
Option C: Out of Scope
Explain the problem out loud. Often the explanation reveals the solution.
Isolate by dividing code in half repeatedly until you find the issue.
Add logging to understand code flow and data transformations.
Create smallest test case that reproduces the issue.
Find similar working code and compare differences.
Always Update When:
Document:
When truly blocked:
Create comprehensive steering documents for development projects. Generates project-specific standards, git workflows, and technology guidelines in .kiro/steering/ directory.
Effective communication strategies for AI-assisted development. Learn context-first prompting, phased interactions, iterative refinement, and validation techniques to get better results from Claude and other AI coding assistants.
Transform approved requirements into comprehensive technical designs. Define system architecture, component interactions, data models, and interfaces to create a blueprint for implementation.
Comprehensive testing and validation strategies for spec-driven development. Learn phase-specific validation techniques, quality gates, and testing approaches to ensure high-quality implementation.
Transform vague feature ideas into clear, testable requirements using EARS format. Capture user stories, define acceptance criteria, identify edge cases, and validate completeness before moving to design.
Systematic three-phase approach to feature development using Requirements, Design, and Tasks phases. Transforms vague feature ideas into well-defined, implementable solutions that reduce ambiguity, improve quality, and enable effective AI collaboration.