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

Specialists

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 `docs/sdd-guidelines.md` 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

Cross-Cutting for react-sample

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