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.
Provides systematic strategies for diagnosing and resolving common development blockers like spec-reality gaps, dependency issues, unclear requirements, and integration failures. Use when implementation hits unexpected obstacles or requirements need clarification.
/plugin marketplace add jasonkneen/kiro/plugin install kiro-spec-driven@kiro-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
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:
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.