Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• spec-process-guide/examples/troubleshooting-pitfalls.md
• skills/troubleshooting/SKILL.md
• spec-process-guide/execution/troubleshooting.md
• spec-process-guide/templates/checklists.md
• kiro-web-app/src/pages/SystemDocs.tsx
• spec-process-guide/process/design-phase.md
• spec-process-guide/resources/standards.md

Troubleshooting within the spec-driven development process is a systematic approach to diagnosing and resolving common problems that arise during feature implementation. It provides strategies for handling challenges such as spec-reality divergence, dependency blocks, unclear requirements, and performance issues. The goal is not just to fix immediate problems but also to feed insights back into the specification process, improving future development cycles.

This guide covers common pitfalls across the Requirements, Design, and Implementation phases, offering structured resolution paths and prevention strategies. It emphasizes a disciplined approach where problems are documented, assessed, and resolved methodically, ensuring that the specification remains the source of truth. For broader process issues, refer to the Process Guide, and for implementation guidance, see the Implementation Guide.

Sources: skills/troubleshooting/SKILL.md, spec-process-guide/execution/troubleshooting.md, spec-process-guide/examples/troubleshooting-pitfalls.md

General Troubleshooting Process

When an issue is encountered, a general diagnostic process should be followed. This involves isolating the problem, verifying against the established contracts (specs), and then implementing a fix with validation.

The following diagram illustrates the high-level flow for diagnosing an issue.

Sources: skills/troubleshooting/SKILL.md:200-218, spec-process-guide/execution/troubleshooting.md:265-283

Pitfalls and Solutions by Phase

Troubleshooting often begins by identifying which phase of the spec-driven process the issue originates from.

Requirements Phase Pitfalls

Issues in this phase often stem from ambiguity, scope creep, or missing details.

Pitfall	Problem Example	Solution
Vague Requirements	"System should be fast."	Convert subjective terms to measurable criteria (e.g., "System SHALL save changes within 2 seconds"). Use EARS format.
Scope Creep	"Simple login" becomes a full user management system.	Define clear boundaries for the current spec and document "future enhancements" separately.
Missing Edge Cases	Only documenting the "happy path" for a user action.	For each requirement, explicitly consider failure modes, boundary conditions, and system stress behavior.

Sources: spec-process-guide/examples/troubleshooting-pitfalls.md:18-72, spec-process-guide/resources/standards.md:15-68

The recovery strategy for flawed requirements involves stopping work, returning to the requirements phase to address the specific issues, and getting explicit approval before proceeding.

Sources: spec-process-guide/examples/troubleshooting-pitfalls.md:191-197

Design Phase Pitfalls

Design-phase problems include over-engineering, insufficient research, and creating a gap between the design and practical implementation.

Pitfall	Problem Example	Solution
Over-Engineering	Using a microservices architecture for a simple CRUD app.	Review design decisions against actual requirements. Ask, "What's the simplest solution that works?"
Insufficient Research	Assuming a library has capabilities it doesn't.	Validate assumptions with proof-of-concept code during the design phase.
Design-Implementation Gap	A theoretically sound design that is impractical to build.	Review the design for implementation feasibility and add implementation notes for complex parts.

Sources: spec-process-guide/examples/troubleshooting-pitfalls.md:74-121, spec-process-guide/process/design-phase.md:301-309

Common Implementation Issues

This section details common problems encountered during the coding phase and provides structured solutions.

Sources: skills/troubleshooting/SKILL.md, spec-process-guide/execution/troubleshooting.md

Issue 1: Spec and Reality Diverge

This occurs when the implementation context (existing code, APIs) does not match the assumptions made in the specification.

Symptoms:

• Code structure doesn't match spec assumptions.
• APIs are unavailable, deprecated, or work differently than specified.
• Performance characteristics differ from expectations.

Resolution Flow:

Sources: skills/troubleshooting/SKILL.md:24-48, spec-process-guide/execution/troubleshooting.md:25-46

Prevention:

• Validate assumptions with code exploration or prototypes during the design phase.
• Include technical spikes in the task breakdown for uncertain areas.

Sources: skills/troubleshooting/SKILL.md:50-52, spec-process-guide/execution/troubleshooting.md:48-50

Issue 2: Task Dependencies Block Progress

This happens when a task cannot be completed because it depends on another part of the project that is not yet finished.

Resolution Strategies:

Strategy	Description	When to Use
Reorder Tasks	Identify the prerequisite task and complete it first.	A dependency was missed during planning.
Split Tasks	Break the blocked task into smaller pieces and complete the unblocked parts.	The task is too large or partially blocked.
Use Mocking/Stubbing	Create a minimal mock of the dependency to unblock the current task.	The dependency is complex or external.
Parallel Development	Define a clear interface/contract that both dependent and dependency teams can implement against.	The dependency is being developed concurrently.

Sources: skills/troubleshooting/SKILL.md:59-86, spec-process-guide/execution/troubleshooting.md:68-96

Issue 3: Requirements Unclear During Implementation

Ambiguity in requirements discovered during coding can lead to incorrect implementation. The key is to get clarification rather than making assumptions.

Clarification Process:

Sources: skills/troubleshooting/SKILL.md:95-120, spec-process-guide/execution/troubleshooting.md:114-138

Issue 4: Technical Debt Creates Friction

Existing code quality issues can make implementing new features difficult.

Resolution Strategies:

Strategy	Description
Refactor-First	Create separate refactoring tasks and complete them before starting the feature work. Best for bounded, low-risk changes.
Parallel Track	Implement the feature with workarounds while creating a separate, larger refactoring initiative.
Incremental Improvement	Refactor only the parts of the code that are touched for the new feature ("Boy Scout Rule").

Sources: skills/troubleshooting/SKILL.md:127-148, spec-process-guide/execution/troubleshooting.md:157-178

Issue 5: Performance Problems

The implementation is functionally correct but fails to meet performance requirements.

Resolution Process:

1. Measure: Profile the code to identify bottlenecks and quantify the performance gap.
2. Analyze: Determine the root cause (e.g., algorithmic complexity, database inefficiency, network latency).
3. Optimize: Target the biggest bottleneck first, making one change at a time and measuring the impact.
4. Validate: Verify that requirements are met without introducing regressions and add performance tests.

Common Fixes:

Area	Common Solutions
Database	Add indexes, optimize queries, implement caching, batch operations.
Algorithm	Use better data structures, reduce complexity, use lazy loading.
Network	Batch requests, use compression, reduce payload size.

Sources: skills/troubleshooting/SKILL.md:179-204, spec-process-guide/execution/troubleshooting.md:225-263

Issue 6: Scope Creep During Implementation

The tendency to add features or improvements that are not part of the original specification.

The resolution is to recognize when work is going beyond the spec, evaluate if the new work is truly required for the current feature, and decide whether to incorporate it, defer it, or discard it.

Sources: skills/troubleshooting/SKILL.md:220-251, spec-process-guide/execution/troubleshooting.md:285-317

Kiro AI Assistant Troubleshooting

For issues related to the Kiro AI assistant itself, a specific troubleshooting approach is documented. If a user asks for help with a Model Context Protocol (MCP) tool, the recommended first step is to immediately test its behavior with one or more example calls rather than checking its configuration first.

MCP server configuration can be managed in mcp.json files, and the server can be reconnected from the Kiro functionality panel without a full restart.

Sources: kiro-web-app/src/pages/SystemDocs.tsx:70-80

General Debugging Strategies

Several general-purpose debugging strategies are recommended to help isolate and understand problems.

Strategy	Description
Rubber Duck Debugging	Explain the problem out loud to yourself or an inanimate object. The act of articulation often reveals the solution.
Binary Search	Isolate a problem by repeatedly dividing the code or system in half to narrow down where the issue is occurring.
Strategic Logging	Add logging statements to understand the code flow and the state of data at different points in execution.
Minimal Reproduction	Create the smallest possible test case that consistently reproduces the issue.
Compare Working vs. Broken	Find a similar piece of code that works correctly and compare it against the broken implementation to spot differences.

Sources: skills/troubleshooting/SKILL.md:253-268, spec-process-guide/execution/troubleshooting.md:319-334

Summary

Effective troubleshooting is a critical skill in a spec-driven environment. It involves a structured process of identifying, analyzing, and resolving issues while maintaining the integrity of the specification. Key practices include catching issues early, documenting problems and their resolutions, updating specs when reality diverges, and staying focused on the defined requirements. By treating troubleshooting as a feedback loop, teams can improve not only the current implementation but also the quality of future specifications.

Sources: spec-process-guide/execution/troubleshooting.md:353-362