/kiro-spec-design

name: kiro-spec-design
description: Create comprehensive technical design for a specification
metadata:
  shared-rules: "design-principles.md, design-discovery-full.md, design-discovery-light.md, design-synthesis.md, design-review-gate.md"

Technical Design Generator

<background_information>

• **Success Criteria**:
• All requirements mapped to technical components with clear interfaces
• The design makes responsibility boundaries explicit enough to guide task generation and review
• Appropriate architecture discovery and research completed
• Design aligns with steering context and existing patterns
• Visual diagrams included for complex architectures

</background_information>

<instructions>

Execution Steps

Step 1: Load Context

**Read all necessary context**:

• `{{KIRO_DIR}}/specs/$1/spec.json`, `requirements.md`, `design.md` (if exists)
• `{{KIRO_DIR}}/specs/$1/research.md` (if exists, contains gap analysis from `/kiro-validate-gap`)
• Core steering context: `product.md`, `tech.md`, `structure.md`
• Additional steering files only when directly relevant to requirement coverage, architecture boundaries, integrations, runtime prerequisites, security/performance constraints, or team conventions that affect implementation readiness
• Use explicitly requested skills and task-relevant local skills/playbooks, including design, accessibility, and UX. Select by description and read only needed guidance, even for small tasks; preserve required checks and host/project rules.
• Consult relevant domain skills even when building by hand without adopting a new library.
• `{{KIRO_DIR}}/settings/templates/specs/design.md` for document structure
• Read `rules/design-principles.md` from this skill's directory for design principles
• `{{KIRO_DIR}}/settings/templates/specs/research.md` for discovery log structure

**Validate requirements approval**:

• If `-y` flag provided ($2 == "-y"): Auto-approve requirements in spec.json
• Otherwise: Verify approval status (stop if unapproved, see Safety & Fallback)

Step 2: Discovery & Analysis

**Critical: This phase ensures design is based on complete, accurate information.**

1. **Classify Feature Type**:

• **New Feature** (greenfield) → Full discovery required
• **Extension** (existing system) → Integration-focused discovery
• **Simple Addition** (CRUD/UI) → Minimal or no discovery
• **Complex Integration** → Comprehensive analysis required

2. **Execute Appropriate Discovery Process**:

**For Complex/New Features**:

• Read and execute `rules/design-discovery-full.md` from this skill's directory
• Conduct thorough research using WebSearch/WebFetch:
• Latest architectural patterns and best practices
• External dependency verification (APIs, libraries, versions, compatibility)
• Official documentation, migration guides, known issues
• Performance benchmarks and security considerations

**For Extensions**:

• Read and execute `rules/design-discovery-light.md` from this skill's directory
• Focus on integration points, existing patterns, compatibility
• Use Grep to analyze existing codebase patterns

**For Simple Additions**:

• Skip formal discovery, quick pattern check only

Parallel Research (sub-agent dispatch)

The following research areas are independent and can be dispatched as **sub-agents**. The agent should decide the optimal decomposition based on feature complexity — split, merge, add, or skip sub-agents as needed. Each sub-agent returns a **findings summary** (not raw data) to keep the main context clean for synthesis.

**Typical research areas** (adjust as appropriate):

• **Codebase analysis**: Existing architecture patterns, integration points, code conventions
• **External research**: Dependencies, APIs, latest best practices
• **Context loading** (usually main context): Steering files, design principles, discovery rules, templates

For simple additions, skip sub-agent dispatch entirely and do a quick pattern check in main context.

After all findings return, synthesize in main context before proceeding.

3. **Retain Discovery Findings for Step 3**:

• External API contracts and constraints
• Technology decisions with rationale
• Existing patterns to follow or extend
• Integration points and dependencies
• Identified risks and mitigation strategies
• Boundary candidates, out-of-boundary decisions, and likely revalidation triggers

4. **Persist Findings to Research Log**:

• Create or update `{{KIRO_DIR}}/specs/$1/research.md` using the shared template
• Summarize discovery scope and key findings (Summary section)
• Record investigations in Research Log topics with sources and implications
• Document architecture pattern evaluation, design decisions, and risks using the template sections
• If `research.md` already exists, briefly record consulted skills and the guidance used in its existing research notes.
• Use the language specified in spec.json when writing or updating `research.md`

Step 3: Synthesis

**Apply design synthesis to discovery findings before writing.**

• Read and apply `rules/design-synthesis.md` from this skill's directory
• This step requires the full picture from discovery — do not parallelize or delegate to sub-agents
• Record synthesis outcomes (generalizations found, build-vs-adopt decisions, simplifications) in `research.md`

Step 4: Generate Design Draft

1. **Load Design Template and Rules**:

• Read `{{KIRO_DIR}}/settings/templates/specs/design.md` for structure
• Read `rules/design-principles.md` from this skill's directory for principles

2. **Generate Design Draft**:

• **Follow specs/design.md template structure and generation instructions strictly**
• **Boundary-first requirement**: Before expanding supporting sections, make the boundary explicit. The draft must clearly define what this spec owns, what it does not own, which dependencies are allowed, and what changes w