<< All versions

Skill v1.0.0

currentAutomated scan100/100
sebasmzg/sebas.dot/sdd-spec
──Details
PublishedNovember 19, 2026 at 08:09 PM
Content Hashsha256:bf5190bddc5dcc45...
Git SHA22a7ad4f2e73
──Files
Files (1 file, 7.0 KB)
SKILL.md7.0 KBactive
SKILL.md · 231 lines · 7.0 KB

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 | hybrid | none)

Execution and Persistence Contract

Read and follow skills/_shared/persistence-contract.md for mode resolution rules.

  • If mode is engram:

CRITICAL: `mem_search` returns 300-char PREVIEWS, not full content. You MUST call `mem_get_observation(id)` for EVERY artifact. If you skip this, you will work with incomplete data and produce wrong specs.

STEP A — SEARCH (get IDs only — content is truncated):

  1. mem_search(query: "sdd/{change-name}/proposal", project: "{project}") → save ID

STEP B — RETRIEVE FULL CONTENT (mandatory):

  1. mem_get_observation(id: {proposal_id}) → full proposal content (REQUIRED)

DO NOT use search previews as source material.

If specs span multiple domains, concatenate into a single artifact with domain headers.

Save your artifact: `` mem_save( title: "sdd/{change-name}/spec", topic_key: "sdd/{change-name}/spec", type: "architecture", project: "{project}", content: "{your full spec markdown — all domains concatenated}" ) ` topic_key` enables upserts — saving again updates, not duplicates.

(See skills/_shared/engram-convention.md for full naming conventions.)

  • If mode is openspec: Read and follow skills/_shared/openspec-convention.md.
  • If mode is hybrid: Follow BOTH conventions — persist to Engram (single concatenated artifact) AND write domain files to filesystem.
  • If mode is none: Return result only. Never create or modify project files.

What to Do

Step 1: Load Skill Registry

Do this FIRST, before any other work.

  1. Try engram first: mem_search(query: "skill-registry", project: "{project}") → if found, mem_get_observation(id) for the full registry
  2. If engram not available or not found: read .atl/skill-registry.md from the project root
  3. If neither exists: proceed without skills (not an error)

From the registry, identify and read any skills whose triggers match your task. Also read any project convention files listed in the registry.

Step 2: 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 3: Read Existing Specs

IF mode is `openspec` or `hybrid`: If openspec/specs/{domain}/spec.md exists, read it to understand CURRENT behavior. Your delta specs describe CHANGES to this behavior.

IF mode is `engram`: Existing specs were already retrieved from Engram in the Persistence Contract. Skip filesystem reads.

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

Step 4: Write Delta Specs

IF mode is `openspec` or `hybrid`: Create specs inside the change folder:

openspec/changes/{change-name}/
├── proposal.md ← (already exists)
└── specs/
└── {domain}/
└── spec.md ← Delta spec

IF mode is `engram` or `none`: Do NOT create any openspec/ directories or files. Compose the spec content in memory — you will persist it in Step 5.

Delta Spec Format

markdown
# 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):

markdown
# {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.

If mode is engram:

mem_save(
title: "sdd/{change-name}/spec",
topic_key: "sdd/{change-name}/spec",
type: "architecture",
project: "{project}",
content: "{your full spec markdown from Step 4 — all domains concatenated}"
)

If mode is openspec or hybrid: the file was already written in Step 4.

If mode is hybrid: also call mem_save as above (write to BOTH backends).

If you skip this step, the next phase (sdd-tasks) will NOT be able to find your specs and the pipeline BREAKS.

Step 6: Return Summary

Return to the orchestrator:

markdown
## 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 Step
Ready 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.specs from openspec/config.yaml
  • Return a structured envelope with: status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks

RFC 2119 Keywords Quick Reference

KeywordMeaning
MUST / SHALLAbsolute requirement
MUST NOT / SHALL NOTAbsolute prohibition
SHOULDRecommended, but exceptions may exist with justification
SHOULD NOTNot recommended, but may be acceptable with justification
MAYOptional
All versions