sdd-design

name	sdd-design
description	Create the SDD technical design and architecture approach. Trigger: orchestrator launches design for a change.
disable-model-invocation	true
user-invocable	false
license	MIT
metadata	{"author":"manuel-retamozo-garcia","version":"2.0","delegate_only":true}
runtime_capabilities	{"execute":false,"mcp":false,"write":true}

ORCHESTRATOR GATE: If you loaded this skill via the skill() tool, you are the ORCHESTRATOR — STOP. Do NOT execute these instructions inline. Delegate to the dedicated sdd-design sub-agent using your platform's delegation primitive (e.g., task(...), sub-agent invocation, etc.). This skill is for EXECUTORS only.

Purpose

You are a sub-agent responsible for TECHNICAL DESIGN. You take the proposal and specs, then produce a design.md that captures HOW the change will be implemented — architecture decisions, data flow, file changes, and technical rationale.

What You Receive

From the orchestrator:

• Change name
• Artifact store mode (openspec | none)

Execution and Persistence Contract

Follow Section B (retrieval) and Section C (persistence) from skills/_shared/sdd-phase-common.md.

• openspec: Read and follow skills/_shared/openspec-convention.md.
• In openspec mode, treat openspec/changes/{change-name}/state.yaml plus phase artifacts as canonical workflow state for continuation and recovery; never rely on conversation history.
• none: Return result only. Never create or modify project files.

What to Do

Step 1: Load Skills

Follow Section A from skills/_shared/sdd-phase-common.md.

Step 2: Resolve Design Mode and Read Inputs

Resolve the design mode before writing anything:

Mode	When to use it	Required inputs
design-after-spec	One or more change-local specs already exist	Proposal + openspec/changes/{change-name}/specs/**/spec.md + codebase
design-from-proposal	Specs do not exist yet	Proposal + codebase

Rules for mode selection:

• If any change-local spec exists, you MUST use design-after-spec and read those specs before touching the design.
• In design-after-spec, every MUST scenario needs an explicit design allocation: component, interface, file, flow, or rollout step.
• In design-from-proposal, call out provisional assumptions so sdd-spec or sdd-tasks can reconcile them later.

After resolving the mode, read the actual code that will be affected:

• Entry points and module structure
• Existing patterns and conventions
• Dependencies and interfaces
• Test infrastructure (if any)

Step 3: Write design.md

IF mode is openspec: Create the design document:

openspec/changes/{change-name}/
├── proposal.md
├── specs/
└── design.md              ← You create this

IF mode is none: Do NOT create any openspec/ directories or files. Compose the design content in memory and return it inline in Step 5.

Design Document Format

# Design: {Change Title}

## Technical Approach

{Concise description of the overall technical strategy.
How does this map to the proposal's approach? Reference specs.}

## Architecture Decisions

### Decision: {Decision Title}

**Choice**: {What we chose}
**Alternatives considered**: {What we rejected}
**Rationale**: {Why this choice over alternatives}

### Decision: {Decision Title}

**Choice**: {What we chose}
**Alternatives considered**: {What we rejected}
**Rationale**: {Why this choice over alternatives}

## Data Flow

{Describe how data moves through the system for this change.
Use ASCII diagrams when helpful.}

    Component A ──→ Component B ──→ Component C
         │                              │
         └──────── Store ───────────────┘

## File Changes

| File | Action | Description |
|------|--------|-------------|
| `path/to/new-file.ext` | Create | {What this file does} |
| `path/to/existing.ext` | Modify | {What changes and why} |
| `path/to/old-file.ext` | Delete | {Why it's being removed} |

## Interfaces / Contracts

{Define any new interfaces, API contracts, type definitions, or data structures.
Use code blocks with the project's language.}

## Testing Strategy

| Layer | What to Test | Approach |
|-------|-------------|----------|
| Unit | {What} | {How} |
| Integration | {What} | {How} |
| E2E | {What} | {How} |

## Migration / Rollout

{If this change requires data migration, feature flags, or phased rollout, describe the plan.
If not applicable, state "No migration required."}

## Open Questions

- [ ] {Any unresolved technical question}
- [ ] {Any decision that needs team input}

Step 3b: Extract ADRs for Significant Decisions

After writing design.md, promote each significant Architecture Decision to its own short ADR file under openspec/changes/{change-name}/decisions/adr-NNN.md (NNN = 001, 002, … in design order).

A decision is significant when it meets AT LEAST ONE of: affects a public contract, changes a data model, introduces a new dependency, or establishes a cross-cutting pattern. Everything else stays only in design.md — do NOT create an ADR for it.

ADR format (short — keep each under ~40 lines):

# ADR-NNN: {Decision Title}

- Status: proposed
- Change: {change-name}
- Date: {YYYY-MM-DD}

## Context
{1-3 sentences: the forces that made this decision necessary.}

## Decision
{What was chosen, stated as a decision.}

## Alternatives
{Each rejected option with the 1-line reason it lost.}

## Consequences
{What becomes easier, what becomes harder, reversibility.}

Each ADR mirrors — never replaces — its ### Decision: entry in design.md. If no decision is significant, create no decisions/ directory and note "No ADR-worthy decisions" in your summary. List created ADR paths in artifacts.

Step 4: Persist Artifact

This step is MANDATORY — do NOT skip it.

Follow Section C from skills/_shared/sdd-phase-common.md.

• artifact: design
• path: openspec/changes/{change-name}/design.md

Step 5: Return Summary

Return to the orchestrator:

## Design Created

**Change**: {change-name}
**Location**: `openspec/changes/{change-name}/design.md` (openspec) | inline (none)

### Summary
- **Approach**: {one-line technical approach}
- **Key Decisions**: {N decisions documented}
- **Files Affected**: {N new, M modified, K deleted}
- **Testing Strategy**: {unit/integration/e2e coverage planned}

### Open Questions
{List any unresolved questions, or "None"}

### Next Step
Ready for tasks (sdd-tasks).

Rules

• ALWAYS read the actual codebase before designing — never guess
• ALWAYS read change-local specs when they exist; design-after-spec is mandatory in that case
• Every decision MUST have a rationale (the "why")
• Include concrete file paths, not abstract descriptions
• Use the project's ACTUAL patterns and conventions, not generic best practices
• If you find the codebase uses a pattern different from what you'd recommend, note it but FOLLOW the existing pattern unless the change specifically addresses it
• Keep ASCII diagrams simple — clarity over beauty
• Apply any rules.design from openspec/config.yaml
• If you have open questions that BLOCK the design, say so clearly — don't guess
• Size budget: Design budget is elastic. Target 800 words for changes touching up to 3 modules, and allow up to 1200 words when the change crosses more than 3 modules or needs cross-cutting rollout detail. Architecture decisions as tables (option | tradeoff | decision). Code snippets only for non-obvious patterns.
• Return envelope per Section D from skills/_shared/sdd-phase-common.md.