sdd-design

name	sdd-design
description	Orchestrate design document creation using specialist skills. Use when: starting design phase, merging specialist outputs, resolving design conflicts. Triggers: "create design", "design phase", "merge design", "design skeleton"

SDD Design Orchestrator

Coordinate specialist skills to produce a complete design document.

Role

Do	Don't
Create skeleton structure	Write implementation details
Assign sections to specialists	Make design decisions
Map REQs to sections	Choose libraries or patterns
Merge specialist outputs	Override specialist decisions
Resolve conflicts between specialists	Skip specialist review

Specialists

Skill	Domain	Invocation
sdd-design-frontend	Component architecture, state, patterns	After skeleton
sdd-design-uiux	Layout, responsive, accessibility	After skeleton
sdd-design-security	Threats, sandboxing, validation	After skeleton
sdd-design-perf	Bundle size, lazy loading, caching	After skeleton

Workflow

Phase 1: Skeleton
    │
    ├─→ Phase 2: Specialists (parallel)
    │       ├── frontend
    │       ├── uiux  
    │       ├── security
    │       └── perf
    │
    └─→ Phase 3: Merge

Instructions

Phase 1: Create Skeleton

1. Read requirements document

   packages/{package}/spec/{package}.requirements.md
   

2. Create design file

   packages/{package}/spec/{package}.design.md
   

3. Write skeleton using template:

---
title: "{Package} Design"
author: Claude
date: {YYYY-MM-DD}
version: 1.0.0
status: draft
depends_on:
  - packages/{package}/spec/{package}.requirements.md@{version}
---

# {Package} Design

## Overview

Brief description of the design approach.

@derives: (list all REQ IDs)

**Status:** draft

## Component Architecture

@derives: {REQ-IDs}

<!-- sdd-design-frontend writes this section -->

**Status:** pending

## UI/UX Design

@derives: {REQ-IDs}

<!-- sdd-design-uiux writes this section -->

**Status:** pending

## Security Considerations

@derives: {REQ-IDs}

<!-- sdd-design-security writes this section -->

**Status:** pending

## Performance Strategy

@derives: {REQ-IDs}

<!-- sdd-design-perf writes this section -->

**Status:** pending

## Decisions Log

| ID | Decision | Rationale | Owner |
|----|----------|-----------|-------|
| | | | |

## Cross-Cutting Concerns

> **Note:** Extension to sdd-guidelines for specialist coordination.

| Concern | Primary | Reviewer | Status |
|---------|---------|----------|--------|
| Accessibility | uiux | frontend | pending |
| Error handling | frontend | security | pending |
| Loading states | uiux | perf | pending |

4. Initialize state file

# .sdd/state.yaml (add to existing)
documents:
  design:
    status: draft
    sections:
      component-architecture:
        status: pending
        owner: sdd-design-frontend
      uiux:
        status: pending
        owner: sdd-design-uiux
      security:
        status: pending
        owner: sdd-design-security
      perf:
        status: pending
        owner: sdd-design-perf

5. Map REQs to sections

   Read each requirement and determine which section(s) address it:

   Section	Typical REQs
   Component Architecture	Structure, data flow, patterns
   UI/UX Design	Layout, interaction, responsive
   Security	User input, code execution, XSS
   Performance	Loading, bundle size, caching

6. Fill @derives for each section

Phase 2: Invoke Specialists

Invoke all specialists in parallel. Each specialist:

• Reads the skeleton
• Reads assigned REQs
• Writes their section
• Adds decisions to Decisions Log

Invocation format:

Use sdd-design-{specialist} to write the {Section Name} section 
for packages/{package}/spec/{package}.design.md

Phase 3: Merge

After all specialists complete:

1. Collect outputs

   • Each specialist's section content
   • Decisions added to log

2. Check conflicts

   Conflict Type	Detection	Resolution
   Library choice	Same need, different lib	Perf wins unless security concern
   Pattern choice	Same problem, different pattern	Frontend decides
   Layout vs Perf	UX wants X, Perf says too heavy	UX for primary flow, Perf for edge
   Any vs Security	Security flags risk	Security wins, find alternative

3. Review cross-cutting concerns

   For each concern:

   • Primary owner wrote the approach
   • Reviewer validates from their perspective
   • Mark status: approved or needs-revision

4. Ensure consistency

   • Terminology matches across sections
   • No contradicting decisions
   • All REQs have @derives coverage

5. Update status

   • If no conflicts: status: verified
   • If unresolved: status: blocked + note

Example: react-sample

Skeleton REQ Mapping

Section	REQs
Component Architecture	REQ-REACT-001, 002, 003, 004
UI/UX Design	REQ-REACT-002, 003, 005
Security Considerations	REQ-REACT-004
Performance Strategy	REQ-REACT-003, 004

Cross-Cutting for react-sample

Concern	Primary	Reviewer	Notes
Accessibility	uiux	frontend	Keyboard nav for playground
Error handling	frontend	security	Editable code errors
Loading states	uiux	perf	Code viewer lazy load
Code display	frontend	perf	Syntax highlighter choice
User input	frontend	security	Props playground inputs

Verification

After merge:

• All REQs appear in at least one @derives
• No section has placeholder comments
• Decisions Log has entries from each specialist
• Cross-cutting concerns all approved
• No contradicting decisions
• Frontmatter complete (title, version, depends_on)

Conflict Escalation

If specialists can't resolve:

1. Document both options in Decisions Log
2. Set decision status to escalated
3. Flag for human review:

   > ⚠️ **Escalated:** {description}
   > Options: A) {option1} B) {option2}
   > Blocked until human decision.
   

References

• reference/section-templates.md — Detailed section structures