---
description: Create comprehensive technical design for a specification
allowed-tools: Bash, Glob, Grep, LS, Read, Write, Edit, MultiEdit, Update, WebSearch, WebFetch
argument-hint: <feature-name> [-y]
---

# Technical Design Generator

<background_information>
- **Role**: Translate approved requirements into a thorough, implementation-ready technical design document that guides consistent execution across all contributors.
- **Success Criteria**:
  - Every requirement is traceable to at least one design component or interface
  - Discovery depth matches feature complexity — no gaps in critical research
  - The design aligns with established steering patterns and project conventions
  - Mermaid diagrams are included where they genuinely reduce ambiguity
</background_information>

<instructions>
## Core Task
Produce the technical design document for feature **$1** from its approved requirements.

## Execution Steps

### Step 1: Load Context

**Read all required inputs**:
- `{{SDD_DIR}}/specs/$1/spec.json`, `requirements.md`, and `design.md` (if it already exists)
- The entire `{{SDD_DIR}}/steering/` directory (core + all custom files) for full project memory
- `{{SDD_DIR}}/settings/templates/specs/design.md` for document structure
- `{{SDD_DIR}}/settings/rules/design-principles.md` for authoring rules
- `{{SDD_DIR}}/settings/templates/specs/research.md` for the discovery log structure

**Gate on requirements approval**:
- If `-y` is provided ($2 == "-y"): mark requirements as approved in `spec.json` and continue
- Otherwise: check approval status — halt if requirements are not yet approved (see Safety & Fallback)

### Step 2: Discovery and Research

**This phase anchors the design in verified, current information.**

**Classify the feature**:
- **Greenfield / New Feature** → Full discovery is required
- **Extension of Existing System** → Integration-focused discovery
- **Simple CRUD or UI Addition** → Minimal check only; skip formal discovery
- **Complex Integration** → Comprehensive multi-system analysis required

**Run the appropriate discovery process**:

For **Greenfield or Complex** features:
- Read and follow `{{SDD_DIR}}/settings/rules/design-discovery-full.md`
- Use WebSearch and WebFetch to verify:
  - Latest architectural patterns for the problem domain
  - External API contracts, authentication, rate limits, and known issues
  - Dependency versions and compatibility with the existing stack
  - Security and performance considerations from official sources

For **Extension** features:
- Read and follow `{{SDD_DIR}}/settings/rules/design-discovery-light.md`
- Use Grep to identify existing patterns, integration points, and backward compatibility constraints

For **Simple Additions**:
- Perform a quick pattern check only; skip the formal discovery process

**Capture discovery findings**:
- External API contracts and constraints discovered
- Technology decisions and the rationale behind each
- Existing patterns that should be preserved or extended
- Identified integration points and hard dependencies
- Risks surfaced and proposed mitigations
- Candidate architecture patterns and boundary options
- Parallelization opportunities and dependency chains for future task generation

**Write findings to the research log**:
- Create or update `{{SDD_DIR}}/specs/$1/research.md` using the shared template
- Record the discovery scope and key findings in the Summary section
- Log each investigation topic with sources consulted and design implications
- Document architecture pattern evaluation, selected approach, and rejected alternatives
- Use the language from `spec.json` throughout

### Step 3: Generate the Design Document

1. **Load the design template and principles**:
   - Read `{{SDD_DIR}}/settings/templates/specs/design.md`
   - Read `{{SDD_DIR}}/settings/rules/design-principles.md`

2. **Author the design document**:
   - Follow the template structure and its generation instructions exactly
   - Integrate all discovery findings into component definitions, interface contracts, technology stack, and risk sections
   - If a prior `design.md` exists, treat it as reference context and merge rather than discard
   - Apply all design rules: type safety, visual communication standards, formal tone
   - Use the language specified in `spec.json`
   - Ensure sections use updated heading names: "Architecture Pattern & Boundary Map", "Technology Stack & Alignment", "Components & Interface Contracts"
   - Extended investigation notes belong in `research.md`; `design.md` must remain self-contained for reviewers

3. **Update specification metadata** in `spec.json`:
   - Set `phase: "design-generated"`
   - Set `approvals.design.generated: true` and `approvals.design.approved: false`
   - Set `approvals.requirements.approved: true`
   - Refresh `updated_at` timestamp

## Critical Constraints
- **Type Safety**: Enforce strong typing aligned with the project's language. For TypeScript, never use `any`; use precise types, generics, and discriminated unions. For Python and similar, apply type annotations at all public boundaries.
- **Current Information**: Verify external dependencies and best practices via WebSearch/WebFetch before including them in the design
- **Steering Alignment**: Honor existing architectural decisions and conventions from the steering context
- **Template Adherence**: Follow `design.md` template structure strictly — do not improvise section names or order without clear reason
- **Architecture Only**: Interfaces and contracts only — no implementation code in the design document
- **Numeric Requirement IDs**: Use only numeric IDs as defined in `requirements.md` (e.g., `1.1`, `2.3`) — never invent new IDs or use alphabetic references
</instructions>

## Tool Guidance
- **Read first**: Load spec, steering, templates, and rules before taking any action
- **Research proactively**: Use WebSearch/WebFetch for external dependencies, library docs, and best practices
- **Grep the codebase**: Find existing patterns and integration surfaces before designing new ones
- **Write last**: Produce `design.md` and `research.md` only after all discovery and analysis are complete

## Output Description

**Command output summary** (separate from the design document itself):

Provide a concise report in the language specified in `spec.json`:

1. **Status**: Confirm the design document was generated at `{{SDD_DIR}}/specs/$1/design.md`
2. **Discovery Executed**: State which discovery process was used (full / light / minimal) and why
3. **Key Insights**: 2–3 critical findings from `research.md` that shaped the design
4. **Research Log**: Confirm `research.md` was created or updated
5. **Next Action**: Guide the user on the approval workflow

**Format**: Concise Markdown under 200 words — this is the command summary, not the design document itself.

## Safety & Fallback

### Error Scenarios

**Requirements Not Approved**:
- **Halt**: Design cannot proceed without approved requirements
- **Message**: "Requirements are not yet approved. Approval is required before design generation."
- **Suggested Action**: "Run `/sdd:spec-design $1 -y` to auto-approve requirements and proceed immediately"

**Requirements Document Missing**:
- **Halt**: The requirements document must exist before design begins
- **Message**: "No `requirements.md` found at `{{SDD_DIR}}/specs/$1/requirements.md`"
- **Suggested Action**: "Run `/sdd:spec-requirements $1` to generate requirements first"

**Template Missing**:
- **Message**: "Design template not found at `{{SDD_DIR}}/settings/templates/specs/design.md`"
- **Suggested Action**: "Verify repository setup or restore the missing template"
- **Fallback**: Apply a minimal inline structure with a visible warning

**Steering Context Absent**:
- **Warning**: "Steering directory is empty or missing — the design may not reflect project conventions"
- **Continue**: Proceed with generation but note the limitation prominently

**Discovery Complexity Unclear**:
- **Default**: Execute the full discovery process (`{{SDD_DIR}}/settings/rules/design-discovery-full.md`)
- **Rationale**: Over-researching is safer than missing critical context

**Non-Numeric Requirement IDs**:
- **Halt**: If `requirements.md` uses non-numeric headings (e.g., "Requirement A"), stop and instruct the user to correct the IDs before proceeding

### Next Phase: Task Generation

**When Design Is Approved**:
- Review the generated document at `{{SDD_DIR}}/specs/$1/design.md`
- Optionally run `/sdd:validate-design $1` for an interactive quality review
- Then run `/sdd:spec-tasks $1 -y` to generate implementation tasks

**When Changes Are Needed**:
- Provide specific feedback and re-run `/sdd:spec-design $1`
- The existing design will be used as reference in merge mode

**Note**: Design approval is mandatory before task generation begins.

think hard
