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-new is the entry point for every SDD change. Give it a plain-language description or a ticket ID, and it explores the codebase and creates a proposal.md without requiring you to run explore and propose separately. Use it whenever you are starting a brand-new feature, bugfix, or refactor.

​
Usage

/sdd-new "add user authentication"   # Start from a description
/sdd-new TICKET-123                  # Start from a ticket ID

​
Prerequisites

  • openspec/ initialized — run /sdd-init if it doesn’t exist yet
  • openspec/config.yaml must be present

​
What it does

1

Choose a change name

Derives a short kebab-case name from the description or ticket ID and creates the working directory:
mkdir -p openspec/changes/{change-name}
Naming examples:
  • "Add user export" → user-export
  • TICKET-123 → ticket-123-short-description
2

Explore the codebase

Runs the explore phase (read-only). Before scanning current code, it first recalls past decisions from openspec/INDEX.md, openspec/specs/, and openspec/changes/archive/ to surface prior choices in the same domain. Then reads the live codebase to identify:
  • Existing patterns related to the change
  • Files that will likely be affected
  • Canonical specs already recorded in openspec/specs/
Exploration findings are written to openspec/changes/{change-name}/notes.md for use in the proposal step.
3

Create proposal.md

Runs the propose phase. Reads notes.md plus any steering files in openspec/steering/ to fill in the proposal. If information is missing, asks targeted clarifying questions before generating the document. Only writes proposal.md once all sections can be substantively completed.

​
Output

Two files are created under openspec/changes/{change-name}/:
FileDescription
notes.mdExploration findings: prior decisions, relevant files, existing patterns, constraints
proposal.mdFull change proposal ready for review
The proposal.md follows this structure: 
# Proposal: {Title}

## Metadata
- **Change:** {change-name}
- **Ticket:** {TICKET-ID or N/A}
- **Date:** {YYYY-MM-DD}

## Context
{Why this change is needed now. Business or technical trigger.}

## Problem
{What is wrong or missing. Observable symptoms or pain points.}

## Scope
**In scope:**
- {what this change includes}

**Out of scope:**
- {what this change explicitly does NOT include}

## Proposed Solution
{High-level approach. Enough detail to evaluate feasibility.}

## Alternatives Discarded
| Alternative | Reason discarded |
|-------------|-----------------|
| {option}    | {why not}       |

## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|

## Impact
- **Files affected:** {estimate}
- **Domains:** {list}
- **Tests:** {what needs testing}

## Dependencies
- {External services, teams, or changes that block this. "None" if independent.}

## Acceptance Criteria
- [ ] {Concrete, verifiable condition 1}
- [ ] {Concrete, verifiable condition 2}

​
Skill metadata

PropertyValue
model_hintsonnet
requiresopenspec/config.yaml
producesopenspec/changes/{change}/proposal.md, openspec/changes/{change}/notes.md

​
Next steps

Once proposal.md is reviewed and approved, run /sdd-continue to advance to the spec phase. /sdd-continue detects which artifacts exist and automatically runs the next skill in sequence.
For small changes with a clear scope, consider /sdd-ff instead. It runs propose + spec + design + tasks in a single pass without pausing between phases.

Build docs developers (and LLMs) love

Get started for freeTalk to us