# Spec Format > How to write SDD specifications - EARS syntax, delta format, requirement structure - Skill: `shanepadgett/spec-format` (Agent Skill) - Install (CLI): `npx skillmds@latest add shanepadgett/spec-format` - Raw SKILL.md: https://api.skillmd.com/api/skills/shanepadgett/spec-format/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: shanepadgett (https://skillmd.com/u/shanepadgett) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/shanepadgett/spec-format --- # Spec Format This skill covers how to write and structure SDD specifications. ## Spec File Structure Canonical specs (post-finish) live under the configured canonical spec root (`.ae-config.json` `specRoot`, default `docs/specs`). Discover canonical spec paths with `ae sdd spec list` (no flag by default). Change-set specs for a given change set live under `changes//specs/` and may be nested by domain/subdomain. ```text docs/specs/ / / .md ``` ## Capability Spec Format Each capability spec follows this structure: ```markdown # ## Overview Brief description of what this capability does and why it exists. ## Access (optional) Include this section only when access constraints are meaningful for the capability. > Authenticated or > Public Projects define their own access levels in a platform-level spec (e.g., `auth-gating.md`). ## Dependencies (optional) Optional section listing dependencies on other specs or external systems. ## Requirements Requirements as a bulleted list. Optional grouping headings (### Group Name) for organization. ### - The system SHALL . - WHEN the system SHALL . ### - WHILE the system SHALL . ``` ### Topic headings (groups) Under `## Requirements`, group headings are simply whatever the next heading level down is: - In `kind: new` specs, groups/topics are typically `### ` - In `kind: delta` specs, groups/topics live under `### ADDED/MODIFIED/REMOVED`, so topics are `#### ` `Entry` and `Exit` are just common topic names for user-facing or system-facing flows (they are not special section types). Example (new spec): ```markdown ## Requirements ### Entry - WHEN a user navigates to the system SHALL . ### Exit - WHEN completes the system SHALL redirect to . ``` ### Surface-Agnostic Language Use action-oriented but surface-agnostic language in Entry/Exit: | Prefer | Avoid | |--------|-------| | "navigates to" | "clicks link to" | | "initiates sign-out" | "clicks sign-out button" | | "requests deletion" | "submits the delete form" | The spec describes *what the user intends to do*, not *how they physically do it*. ## EARS Syntax Requirements use EARS (Easy Approach to Requirements Syntax) patterns. Clauses always appear in the same order: `WHILE `, `WHEN `, then `the system SHALL `. Omit clauses you do not need. | Pattern | Template | Use When | |---------|----------|----------| | Ubiquitous | The system SHALL ``. | Always true, no specific trigger or state | | Event-driven | WHEN `` the system SHALL ``. | Response to a discrete event | | State-driven | WHILE `` the system SHALL ``. | Behavior that applies during a sustained state | | Unwanted behavior | IF `` THEN the system SHALL ``. | Errors, failures, edge cases | | Optional feature | WHERE `` is present the system SHALL ``. | Behavior tied to optional capabilities | | Complex | WHILE ``, WHEN `` the system SHALL ``. | Both a state and a trigger are required | ### Pattern selection guide - Start with the scope: if it is always true, use **Ubiquitous**. - If a sustained condition limits the behavior, use **State-driven**. - If a discrete event triggers the behavior, use **Event-driven**. - If both a state and a trigger apply, use **Complex** (WHILE + WHEN). - If you are describing error handling, use **Unwanted behavior** instead of nesting IF inside WHEN. - If behavior only applies when a feature is included, use **Optional feature**. ### Examples - The system SHALL validate all user input before processing. - WHEN the user submits the form the system SHALL save the data. - WHILE in maintenance mode the system SHALL reject new connections. - IF the database connection fails THEN the system SHALL retry with exponential backoff. - WHERE two-factor auth is enabled the system SHALL require a verification code. - WHILE the user is authenticated, WHEN a session expires the system SHALL prompt for re-authentication. ## Change Set Specs (`changes//specs/`) All change set specs live in `changes//specs/` and MUST include YAML frontmatter: ### Validation (required) After you `write` or `edit` any change-set spec under `changes//specs/**/*.md`, you **MUST** run the validator command against the exact file you changed. - Run: `ae sdd spec validate --path ` If validation fails: - You MUST fix the spec content. - You MUST re-run the validator. - Repeat until it prints `OK`. ```markdown --- kind: new | delta --- ``` ### Optional frontmatter fields Change-set specs MAY include additional YAML frontmatter fields when helpful. This is intentionally extensible for future tooling. #### `depends_on` (optional) Use `depends_on` to express spec-to-spec dependencies in a machine-readable form: ```yaml --- kind: new depends_on: - docs/specs//<...>/.md --- ``` Prefer using canonical paths returned by `ae sdd spec list` even when the dependency is being modified in the current change set. ### `kind: new` Use `kind: new` when the spec does not exist in canonical yet. Write it like a normal spec. Do NOT use delta markers or delta sections. ### `kind: delta` Use `kind: delta` when the spec modifies an existing canonical spec. `kind: delta` specs use section buckets (NOT blockquote markers): - `### ADDED` - `### MODIFIED` - `### REMOVED` Under each bucket, use `#### ` headings. For MODIFIED topics, requirements MUST be represented as adjacent Before/After blocks: ```markdown ### MODIFIED #### **Before:** - The system SHALL . **After:** - The system SHALL . ``` For ADDED topics: ```markdown ### ADDED #### - The system SHALL . ``` For REMOVED topics: ```markdown ### REMOVED #### - The system SHALL . **Reason:** ``` ### Where ADDED/MODIFIED/REMOVED may appear Only use `### ADDED/MODIFIED/REMOVED` inside `## Requirements` and `## Access` (if `## Access` is present). - `## Access` is optional; omit it for foundational/mechanism specs (e.g., navigation, rate limiting). - When `## Access` is present in a delta spec, do not add `####` topics under it; put the Before/After or bullets directly under the corresponding `###` bucket. ## RFC 2119 Keywords Requirements use RFC 2119 language: - **SHALL** - Absolute requirement - **SHALL NOT** - Absolute prohibition - **SHOULD** - Recommended but not required - **SHOULD NOT** - Discouraged but not prohibited - **MAY** - Optional Prefer SHALL for most requirements. Use SHOULD/MAY sparingly when behavior is recommended or optional. Do not use SHALL to avoid choosing the right EARS pattern. ## Writing Good Requirements 1. **One requirement per bullet** - Don't combine multiple requirements 2. **Active voice** - "The system SHALL validate" not "Validation shall be performed" 3. **Testable** - Requirements should be verifiable 4. **Implementation-agnostic** - Describe WHAT, not HOW 5. **No ambiguity** - Avoid words like "appropriate", "reasonable", "user-friendly" 6. **Use EARS patterns** - Pick the appropriate pattern for the requirement type ## Referencing Requirements Tasks, plans, and reconciliation reference requirements by quoting the exact EARS line from the spec. Example in tasks.md: ```markdown **Requirements:** - "WHEN the user submits the form the system SHALL save the form data." - "IF validation fails THEN the system SHALL display error messages." ``` ## Flat vs Grouped Delta Specs **Flat:** One delta file per modified capability (default) ```text changes//specs/auth/login.md changes//specs/auth/logout.md ``` **Grouped:** Multiple related changes in one file (for tightly coupled changes) ```text changes//specs/auth/session-management.md # covers login + logout + refresh ``` Use grouped only when changes are truly interdependent and reviewing separately would lose context.