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-propose creates the proposal.md that anchors the rest of the SDD workflow. It analyzes your input against every required proposal section, asks clarifying questions for anything missing, and only generates the document once all sections can be written with real content — not placeholders. If you ran /sdd-new, this phase runs automatically after exploration. Run /sdd-propose directly when you want to draft a proposal without the explore step, or when returning to a change that already has a notes.md.

​
Usage

/sdd-propose "add rate limiting to API"   # Create proposal from description
/sdd-propose TICKET-456                   # Create proposal from ticket ID

​
Prerequisites

  • openspec/ initialized — run /sdd-init if it doesn’t exist
  • Codebase exploration completed or notes.md present (optional but recommended)

​
What it does

1

Determine the change name

If no change directory exists yet, picks a short kebab-case name and creates it:
mkdir -p openspec/changes/{change-name}
2

Gather context

Reads available context before analyzing gaps:
  • openspec/changes/{change-name}/notes.md — exploration findings (if /sdd-explore was run)
  • openspec/steering/ — project conventions and tech stack
3

Analyze completeness

Maps your input against every required proposal section and classifies each as covered, inferable, or missing:
SectionWhat is needed
Context / BackgroundWhy this change is needed now
ProblemWhat is wrong or missing
ScopeWhat is included AND explicitly excluded
Proposed SolutionHigh-level approach
Alternatives DiscardedAt least one alternative and why it was rejected
Risks & MitigationsWhat could go wrong and how to handle it
ImpactFiles/domains affected, what needs testing
DependenciesExternal services, teams, or blocked changes
Acceptance CriteriaConcrete, verifiable conditions for “done”
4

Ask clarifying questions

For every section marked missing, asks specific questions — not generic ones. Groups related questions together (no more than 3–4 at a time). Repeats until every section is covered or inferable. Does not proceed to writing with anything still missing.
5

Generate proposal.md

Writes the full proposal to openspec/changes/{change-name}/proposal.md. All content is in English for token efficiency and searchability.
6

Validate with user

Presents the complete proposal and asks targeted validation questions — scoped to specific sections (scope exclusions, risks, acceptance criteria). Applies feedback to only the changed sections rather than regenerating the whole document.

​
Output

openspec/changes/{change-name}/proposal.md 
# 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 —
implementation details go in design.md.}

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

## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {risk} | {low/medium/high} | {low/medium/high} | {how to handle} |

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

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

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

​
Skill metadata

PropertyValue
model_hintopus
requiresopenspec/config.yaml
producesopenspec/changes/{change}/proposal.md

​
Next steps

With proposal.md approved, run /sdd-continue to advance to the spec phase. /sdd-continue detects the next missing artifact and runs /sdd-spec automatically.
The acceptance criteria in proposal.md become the PR description body during /sdd-verify. Writing them precisely here saves time at the end of the cycle.

Build docs developers (and LLMs) love

Get started for freeTalk to us