Skill v1.0.0
currentAutomated scan100/100version: "1.0.0" name: sdd-spec description: > Write specifications with requirements and scenarios (delta specs for changes). Trigger: When the orchestrator launches you to write or update specs for a change. license: MIT metadata: author: gentleman-programming version: "2.0"
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 (
engram | openspec | none)
Execution and Persistence Contract
Read and follow skills/_shared/persistence-contract.md for mode resolution rules.
- If mode is
engram: Read and followskills/_shared/engram-convention.md. Artifact type:spec. Retrieveproposalas dependency. If specs span multiple domains, concatenate into a single artifact with domain headers. - If mode is
openspec: Read and followskills/_shared/openspec-convention.md. - If mode is
none: Return result only. Never create or modify project files.
What to Do
Step 1: Identify Affected Domains
From the proposal's "Affected Areas", determine which spec domains are touched. Group changes by domain (e.g., auth/, payments/, ui/).
Step 2: Read Existing Specs
If openspec/specs/{domain}/spec.md exists, read it to understand CURRENT behavior. Your delta specs describe CHANGES to this behavior.
Step 3: Write Delta Specs
Create specs inside the change folder:
openspec/changes/{change-name}/├── proposal.md ← (already exists)└── specs/└── {domain}/└── spec.md ← Delta spec
Delta Spec Format
# Delta for {Domain}## ADDED Requirements### Requirement: {Requirement Name}{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}{New description — replaces the existing one}(Previously: {what it was before})#### Scenario: {Updated 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 4: Return Summary
Return to the orchestrator:
## 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}### Next StepReady for design (sdd-design). If design already exists, ready for tasks (sdd-tasks).
Rules
- ALWAYS use Given/When/Then format for scenarios
- ALWAYS use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) for requirement strength
- 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
- 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
- Apply any
rules.specsfromopenspec/config.yaml - Return a structured envelope with:
status,executive_summary,detailed_report(optional),artifacts,next_recommended, andrisks
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 |