sdd-spec

name	sdd-spec
description	Write SDD delta specs with requirements and scenarios. Trigger: orchestrator launches spec work 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-spec 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 writing SPECIFICATIONS. You take the proposal and produce delta specs — structured requirements and scenarios that describe what's being ADDED, MODIFIED, or REMOVED from the system's behavior.

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: Identify Affected Domains

Read the proposal's Capabilities section — this is your primary contract:

FOR EACH entry under "New Capabilities":
├── This becomes a NEW full spec: openspec/changes/{change-name}/specs/<capability-name>/spec.md
├── Write a complete spec (not a delta) — no existing behavior to reference
└── NEVER write directly to openspec/specs/ during sdd-spec; archive promotes it later

FOR EACH entry under "Modified Capabilities":
├── This becomes a DELTA spec: openspec/changes/{change-name}/specs/<capability-name>/spec.md
└── Read existing openspec/specs/<capability-name>/spec.md first — your delta modifies it

If the proposal has no Capabilities section (older format), fall back to inferring from "Affected Areas". But always prefer the explicit Capabilities mapping when present.

Step 3: Read Existing Specs

IF mode is openspec: If openspec/specs/{domain}/spec.md exists, read it to understand CURRENT behavior before writing a modified-domain delta. New domains stay change-local and do not need a main-spec read.

IF mode is none: Skip — no existing specs to read.

Step 4: Write Delta Specs

IF mode is openspec: Create specs inside the change folder:

openspec/changes/{change-name}/
├── proposal.md              ← (already exists)
└── specs/
    └── {domain}/
  └── spec.md          ← Change-local spec (delta for existing domains, full spec for new domains)

For NEW capabilities, this change-local full spec is temporary by design. sdd-archive is the only phase allowed to promote it into openspec/specs/{domain}/spec.md.

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

MODIFIED Requirements Workflow (CRITICAL — read before writing deltas)

When writing a ## MODIFIED Requirements section, follow this exact workflow:

1. Locate the requirement in openspec/specs/{domain}/spec.md
2. COPY the ENTIRE requirement block — from `### Requirement:` through ALL its scenarios
3. PASTE it under `## MODIFIED Requirements`
4. EDIT the copy to reflect the new behavior
5. Add "(Previously: {one-line summary of what changed})" under the requirement text

Why copy-full-then-edit?
→ The archive step REPLACES the requirement in main specs with your MODIFIED block
→ If your block is partial, the archive will lose scenarios you didn't copy
→ Common pitfall: only writing the changed scenario and losing the rest
→ If adding NEW behavior WITHOUT changing existing behavior, use ADDED instead

Delta Spec Format

# Delta for {Domain}

## ADDED Requirements

### Requirement: {Requirement Name} {#REQ-{domain}-{NNN}}

{Description using RFC 2119 keywords: MUST, SHALL, SHOULD, MAY}

The system {MUST/SHALL/SHOULD} {do something specific}.

#### Scenario: {Happy path scenario}

- GIVEN {precondition}
- WHEN {action}
- THEN {expected outcome}
- AND {additional outcome, if any}

#### Scenario: {Edge case scenario}

- GIVEN {precondition}
- WHEN {action}
- THEN {expected outcome}

## MODIFIED Requirements

### Requirement: {Existing Requirement Name}

{Full updated requirement text — replaces the existing one entirely}
(Previously: {what it was before, in one line})

#### Scenario: {Unchanged scenario — keep if still valid}

- GIVEN {precondition}
- WHEN {action}
- THEN {outcome}

#### Scenario: {Updated or new scenario}

- GIVEN {updated precondition}
- WHEN {updated action}
- THEN {updated outcome}

## REMOVED Requirements

### Requirement: {Requirement Being Removed}

(Reason: {why this requirement is being deprecated/removed})

For NEW Specs (No Existing Spec)

If this is a completely new domain, create a FULL spec (not a delta):

# {Domain} Specification

## Purpose

{High-level description of this spec's domain.}

## Requirements

### Requirement: {Name}

The system {MUST/SHALL/SHOULD} {behavior}.

#### Scenario: {Name}

- GIVEN {precondition}
- WHEN {action}
- THEN {outcome}

Step 5: Persist Artifact

This step is MANDATORY — do NOT skip it.

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

• artifact: spec
• path: openspec/changes/{change-name}/specs/{domain}/spec.md

Step 5b: Declare Touched Baseline Domains (stale-delta guard — declare-only)

For each delta domain written, add the domain name to a touched_baseline_domains: list in your return envelope (Step 6). You MUST NOT compute or write any SHA-256 fingerprint yourself, and you MUST NOT touch state.yaml's baseline_fingerprints: block — you have no execute tool capable of hashing files.

Immediately after you return status: success, the ORCHESTRATOR computes the SHA-256 of each declared domain's current baseline openspec/specs/{domain}/spec.md (or writes null if no baseline exists yet) and writes it into state.yaml's baseline_fingerprints: block. sdd-archive compares these orchestrator-written fingerprints at merge time to detect that another change moved the baseline first (see skills/_shared/gate-change-collision.md, Baseline fingerprint at archive).

Step 6: Return Summary

Return to the orchestrator:

Before returning, classify all unresolved specification work into the canonical ambiguity signals below. Every successful sdd-spec return MUST emit all four fields both beside the prose envelope and inside the strict json:result-envelope object:

residual_ambiguity: false
public_contract_questions: []
conflicting_requirements: []
missing_acceptance_criteria: []

The strict success fence follows this typed shape (replace summary, paths, next phase, risks, and touched domains with the actual result):

{"status":"success","executive_summary":"Wrote testable delta specifications.","artifacts":["openspec/changes/example/specs/domain/spec.md"],"next_recommended":"sdd-design","risks":"None","skill_resolution":"injected","residual_ambiguity":false,"public_contract_questions":[],"conflicting_requirements":[],"missing_acceptance_criteria":[]}

Use residual_ambiguity: false plus three empty arrays only when the spec is ready for design without clarification. Set the boolean to true or place each unresolved item in its matching string array when clarification is required. Never omit, null, or substitute prose for these fields on status: success.

## Specs Created

**Change**: {change-name}

### Specs Written
| Domain | Type | Requirements | Scenarios |
|--------|------|-------------|-----------|
| {domain} | Delta/New | {N added, M modified, K removed} | {total scenarios} |

### Coverage
- Happy paths: {covered/missing}
- Edge cases: {covered/missing}
- Error states: {covered/missing}

### Touched Baseline Domains
`touched_baseline_domains: [{domain}, ...]` — declare-only; the orchestrator computes and writes `state.yaml.baseline_fingerprints` for each of these after this return.

### Next Step
Ready for design (sdd-design). If design already exists, ready for tasks (sdd-tasks).

residual_ambiguity: {true|false}
public_contract_questions: [{string}, ...]
conflicting_requirements: [{string}, ...]
missing_acceptance_criteria: [{string}, ...]

Rules

• ALWAYS use Given/When/Then format for scenarios
• ALWAYS use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) for requirement strength
• Read the proposal's Capabilities section first — it tells you exactly which spec files to create
• If existing specs exist, write DELTA specs (ADDED/MODIFIED/REMOVED sections)
• If NO existing specs exist for the domain, write a FULL spec
• Every requirement MUST have at least ONE scenario
• Stable REQ ids: every ADDED requirement heading carries a stable id suffix {#REQ-{domain}-{NNN}} (NNN = 001, 002, … unique within the domain, continuing from the highest existing id in the baseline spec). MODIFIED requirements keep their existing id unchanged; ids are never reused after removal. These ids anchor the traceability chain REQ → task → commit → test.
• Include both happy path AND edge case scenarios
• Keep scenarios TESTABLE — someone should be able to write an automated test from each one
• DO NOT include implementation details in specs — specs describe WHAT, not HOW
• MODIFIED requirements MUST be the FULL block — copy entire requirement + all scenarios from main spec, then edit. Partial MODIFIED blocks lose content at archive time.
• If adding new behavior without changing existing behavior → use ADDED, not MODIFIED
• New capabilities ALWAYS stay under openspec/changes/{change-name}/specs/{domain}/spec.md until archive. sdd-spec never writes directly into openspec/specs/.
• Apply any rules.specs from openspec/config.yaml
• Size budget: Spec budget is elastic per domain. Target 650 words or less for each domain file; multi-domain changes may exceed 650 words in aggregate, but each domain still needs concise normative text. Prefer tables over narrative descriptions. Each scenario: 3-5 lines max.
• Return envelope per Section D from skills/_shared/sdd-phase-common.md.
• For status: success, include all four ambiguity signals in the strict JSON fence as typed JSON values as well as in the prose-adjacent envelope.

RFC 2119 Keywords Quick Reference

Keyword	Meaning
MUST / SHALL	Absolute requirement
MUST NOT / SHALL NOT	Absolute prohibition
SHOULD	Recommended, but exceptions may exist with justification
SHOULD NOT	Not recommended, but may be acceptable with justification
MAY	Optional