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-spec creates the behavior specification for a change — it describes what the system does, not how it does it. It reads the approved proposal.md, identifies the affected domain, checks whether a canonical spec already exists, and produces a focused delta spec covering only what changes. Edge cases, validation rules, and error behaviors are clarified interactively before the document is written. Use /sdd-spec after proposal.md is approved and reviewed.

​
Usage

/sdd-spec                  # Spec for the active change
/sdd-spec {change-name}    # Spec for a specific change

​
Prerequisites

  • openspec/changes/{change-name}/proposal.md created and reviewed

​
What it does

1

Read proposal and identify the domain

Reads proposal.md to understand the problem, scope, and proposed solution. From that context, determines the domain (bounded context) affected by the change. Checks whether a canonical spec already exists at openspec/specs/{domain}/spec.md. Creates the target directory:
mkdir -p openspec/changes/{change-name}/specs/{domain}
2

Read existing specs

If openspec/specs/{domain}/spec.md exists, reads it before writing anything. The change spec is a delta — it documents only what is new or different, not a full replacement of the canonical spec. This keeps each spec concise and makes merging straightforward during /sdd-archive.
3

Clarify behavior interactively

Before writing, asks targeted questions to resolve:
  • Edge cases not covered by the proposal
  • Validation rules for inputs and boundaries
  • Error behavior: what error code, message, or fallback applies
  • Any open questions left in the proposal
Uses AskUserQuestion for each unresolved area and waits for answers before proceeding.
4

Write the delta spec

Creates openspec/changes/{change-name}/specs/{domain}/spec.md with all behaviors expressed in Given/When/Then format. All content is written in English.
5

Present and apply feedback

Shows the complete spec and confirms all behaviors are correctly described. Applies feedback and re-presents only the changed sections.

​
Output

openspec/changes/{change-name}/specs/{domain}/spec.md 
# Spec: {Domain} — {Change Title}

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

## Expected Behavior

### Main Case

**Given** {context/precondition}
**When** {action/event}
**Then** {expected result}

### Alternative Cases

| Scenario | Condition | Result |
|----------|-----------|--------|
| {scenario} | {condition} | {result} |

### Errors

| Error | When | Response |
|-------|------|----------|
| {error} | {condition} | {code/message} |

## Business Rules

- **BR-01:** {Verifiable rule}

## Decisions Made

| Decision | Alternative discarded | Reason |
|----------|-----------------------|--------|
| {decision} | {alternative} | {reason} |

## Open / Pending

- [ ] {Unresolved question}

​
Given/When/Then format

Every behavior is expressed as a scenario. For example: 
### User Registration

**Given** a visitor on the registration page
**When** they submit a valid email and password
**Then** the system creates an account and sends a confirmation email

**Given** a visitor on the registration page
**When** they submit an email that already exists
**Then** the system returns a 409 Conflict error
The spec phase is where most bugs are prevented. A precise spec means fewer surprises during implementation — and fewer back-and-forth corrections after code is written. Invest time here.

​
Key concepts

The change spec at openspec/changes/{change-name}/specs/{domain}/spec.md is a delta — it only documents behaviors that are new or modified by this change. The canonical spec at openspec/specs/{domain}/spec.md represents the full current state of the domain. During /sdd-archive, the delta is merged into the canonical, keeping the canonical always up to date.
Specs describe observable behavior at the system boundary: inputs, outputs, errors, and rules. They do not describe classes, methods, algorithms, or database schemas. Those belong in design.md. Keeping specs implementation-free means they stay valid across refactors.

​
Skill metadata

PropertyValue
model_hintsonnet
requiresopenspec/changes/{change}/proposal.md
producesopenspec/changes/{change}/specs/*/spec.md

​
Next steps

With the spec approved, run /sdd-continue to advance to the design phase. /sdd-design will read both proposal.md and specs/{domain}/spec.md to produce the implementation plan.

Build docs developers (and LLMs) love

Get started for freeTalk to us