Ss Write Spec

Write OpenSpec Delta

Generate OpenSpec-compatible delta specs under openspec/changes/<change-id>/. This is a plumbing skill: day-to-day development normally goes through the ss-plan skill, whose Phase 0 runs this same logic automatically.

When To Use

• You need to align capability specs with reviewers before writing a full execution plan.
• You need to adjust delta specs without regenerating the plan.
• The ss-coding or ss-create-pr skill reported missing or invalid delta specs.

Inputs

If none of these is available, ask the user for the proposal, PRD, or requirement text before continuing.

Language of the deltas: write requirement and scenario prose in the same language as the input document (or the project's existing docs, if that's a clearer signal); default to English when neither gives a signal. SHALL/MUST keywords, code identifiers, and file paths always stay in English.

Step 0: Ensure the OpenSpec Skeleton Exists

Check whether openspec/specs/ and openspec/changes/ already exist. If this repository has no OpenSpec structure yet, create it first by following ../ss-references/openspec-skeleton.md, then continue with Step 1 below.

Process

Step 1: Read Context

Read:

• openspec/config.yaml, if present
• all existing openspec/specs/*/spec.md
• active deltas under openspec/changes/*/specs/*/spec.md, excluding archive/
• relevant OpenAPI definitions, if API paths are mentioned
• project guidance files (e.g., AGENTS.md / CLAUDE.md), if present

Step 2: Derive Change ID

Use an explicit --change-id if provided. Otherwise derive a kebab-case id from, in order:

1. the current branch name, stripped of its type prefix, or
2. the proposal title, or
3. the first meaningful requirement sentence.

The id must contain only lowercase letters, digits, and hyphens.

Step 3: Decide Capability Ownership

For each requirement:

• Prefer an existing capability under openspec/specs/.
• Create a new capability only when no existing capability owns the behavior.
• Capability names are kebab-case business noun phrases.
• If ownership is ambiguous, stop and ask the user to confirm. Do not guess.

Step 4: Generate Delta Files

Write one file per capability:

openspec/changes/<change-id>/
├── proposal.md
└── specs/
    └── <capability>/
        └── spec.md

Allowed section headings are exactly:

• ## ADDED Requirements
• ## MODIFIED Requirements
• ## REMOVED Requirements
• ## RENAMED Requirements

Requirement format:

### Requirement: <name>
The system SHALL ...

#### Scenario: <name>
- **WHEN** ...
- **THEN** ...
- **AND** ...

Rules:

• Every Requirement MUST have at least one Scenario.
• Scenario headings MUST be #### Scenario:.
• MODIFIED MUST copy the original Requirement in full, then edit it — don't write a partial diff.
• REMOVED MUST include a Reason and a Migration note.
• RENAMED uses FROM: <old> → TO: <new>.
• Do not write implementation details. Specs describe observable behavior only.

Step 5: Self-Review

Verify:

• every source requirement is represented
• existing capabilities were reused where appropriate
• no placeholder text remains
• every MODIFIED entry is complete
• every REMOVED entry has a Migration note
• OpenAPI paths mentioned in specs match available OpenAPI definitions, when present

Output

Report:

• the change-id
• files written
• capabilities touched
• ADDED / MODIFIED / REMOVED / RENAMED counts
• any user decisions still pending

Suggest the next step: run the ss-plan skill with the same input to generate the execution plan.