Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

/sdd-design converts the approved behavior spec into a concrete implementation plan. It reads proposal.md and specs/{domain}/spec.md, analyzes every file that will need to be created or modified, and produces design.md with a full scope assessment and design decisions. It runs as a non-interactive subagent — it reads artifacts, produces output, and then presents the result for your review. Use /sdd-design after proposal.md and all specs are approved.

​
Usage

/sdd-design                # Design for the active change
/sdd-design {change-name}  # Design for a specific change

​
Prerequisites

  • openspec/changes/{change-name}/proposal.md approved
  • openspec/changes/{change-name}/specs/{domain}/spec.md approved

​
What it does

1

Review context

Reads all available context before writing:
  1. openspec/changes/{change-name}/proposal.md
  2. openspec/changes/{change-name}/specs/{domain}/spec.md
  3. Existing code patterns similar to what needs to be built
2

Scope analysis

Lists every file that will be created or modified. Classifies the result:
SCOPE ANALYSIS:
Files to create:
  - src/...

Files to modify:
  - src/...

Total: N files
Result: [Ideal < 10 / Evaluate 10-20 / Split required > 20]
If the total exceeds 20 files, /sdd-design recommends splitting the change into smaller pieces before continuing. Oversized changes are a risk signal — they are harder to review, harder to roll back, and more likely to touch unintended code paths.
3

Create design.md

Produces the full implementation plan at openspec/changes/{change-name}/design.md. All content is written in English.
4

Validate with user

Presents the design and confirms:
  • Is the technical approach correct?
  • Are all affected files identified?
  • Any design decisions to revisit?
Applies feedback to specific sections without regenerating the whole document.

​
Output

openspec/changes/{change-name}/design.md 
# Design: {Change Title}

## Metadata
- **Change:** {change-name}
- **Date:** {YYYY-MM-DD}
- **Status:** approved

## Technical Summary
{1-2 paragraphs describing the chosen technical approach}

## Architecture
{ASCII diagram or flow description}

## Files to Create
| File | Type | Purpose |
|------|------|---------| 
| `src/...` | {type} | {purpose} |

## Files to Modify
| File | Change | Reason |
|------|--------|--------|
| `src/...` | {what changes} | {why} |

## Scope
- **Total files:** {N}
- **Result:** {Ideal / Evaluate / Split required}

## Design Decisions
| Decision | Alternative | Reason |
|---------|------------|--------|
| {decision} | {alternative} | {reason} |

## Implementation Notes
{Any technical detail the implementer needs to know}

​
Scope thresholds

FilesAssessmentRecommended action
< 10IdealProceed to tasks
10–20EvaluateReview whether the change can be split
> 20Split requiredDesign recommends splitting before continuing
/sdd-design runs as a non-interactive subagent. It reads files and produces the artifact without asking questions mid-execution. Any clarifications needed are surfaced at the validation step after the document is complete.

​
Skill metadata

PropertyValue
model_hintopus
requiresopenspec/changes/{change}/proposal.md, openspec/changes/{change}/specs/*/spec.md
producesopenspec/changes/{change}/design.md

​
Next steps

With design.md approved, run /sdd-continue to advance to the tasks phase. /sdd-tasks reads design.md and converts the file list into an ordered set of atomic tasks — one per file, one per commit.

Build docs developers (and LLMs) love

Get started for freeTalk to us