Sdd Spec

<!-- MEMORY-CONTRACT v1 -->

Memory contract. This command persists across sessions through engram

(registered as an MCP server in this tool). Use this tool's own engram memory

tools to honor the rules below — do not assume any other persistence layer.

>

- Recall before acting: on a continuation keyword ("listo", "dale",

"ready", "where did we leave off"), first search engram for prior work on

this change before starting fresh; summarize what you found, then continue.

- Validate after saving: after any save, search engram back for the key or

a unique phrase — a "saved" tool response is NOT proof. Retry once; if it

still fails, tell the user the save failed. Never report "saved" on the tool

response alone.

- Summarize at close: before ending, write a session summary (goal, work

done, decisions, next steps, files). Recovery is never automatic.

- If engram is unreachable (not installed / not on PATH): emit a visible

warning that engram was not found and that this work will NOT persist. DO NOT

report memory as saved; DO NOT proceed silently as if it had persisted.

Purpose

Specs define WHAT the system must do from the perspective of observable behavior. They do not say how to implement it. They are the source of truth for verification.

Key concept — Delta Specs: Specs are deltas (changes) on top of what already exists, not full replacements.

• If there is no existing spec: I write a complete spec
• If a spec already exists: I write ADDED/MODIFIED/REMOVED sections

Process

Step 0a — Load project context

Load the project's context and conventions if present. Non-blocking.

Step 0b — Domain context preload

After loading project context and before identifying affected domains, I perform an optional, non-blocking domain context preload:

1. List candidates: List all .md files in ai-context/features/, excluding _template.md and any file whose name begins with an underscore. If the directory is absent, skip this step silently. 2. Apply the filename-stem matching heuristic:

• Split the change slug on hyphens to produce stems; discard any single-character stems.
• For each candidate file, compute its domain slug (filename without .md extension).
• A match occurs when: the domain slug appears in the change name, OR any change-name stem appears in the domain slug (case-insensitive comparison).

3. Load matches: If one or more files match, read each file and inject its content as enrichment context before writing the spec. If no file matches, skip silently — do NOT produce an error or warning. 4. Multiple matches: If more than one file matches, load all matching files. 5. Non-blocking contract: This step MUST NEVER produce status: blocked or status: failed. Any file read error is treated as a miss (skip silently). 6. Enrichment note: Feature file content is treated as enrichment context — it surfaces business rules, invariants, and known gotchas that should inform the spec's requirements and THEN clauses. Both feature files and any existing domain specs MUST be read when both are present. 7. Orchestrator reporting: When one or more feature files are loaded, the summary field MUST note that domain context was preloaded (e.g., "domain context loaded from ai-context/features/auth.md"). Each loaded file path MUST appear in the artifacts list (read, not written).

Step 0c — Spec context preload

Load the change's spec scenarios if present. Non-blocking.

Step 1 — Read prior artifacts

I must read:

• The proposal artifact (the WHAT and WHY):
• Read docs/sdd/{change-name}/proposal.md for full content.
• If the disk file is absent (legacy change): search prior work for sdd/{change-name}/proposal and retrieve it.
• If neither exists and prior work is not reachable: proposal content passed inline from the caller.
• ai-context/architecture.md if it exists (to understand the current system)

Step 1 extended — Validate against Supersedes section

After reading the proposal, I perform a Supersedes cross-check before writing any spec:

1. Check for Supersedes section: look for ## Supersedes in the proposal.

• If absent (older archived change): log WARNING: proposal has no Supersedes section — backwards compat mode; skipping validation and proceed without validation.
• If present and states "None — purely additive": skip validation; proceed to Step 2.
• If present with REMOVED or REPLACED items: proceed to step 2 below.

2. For each REMOVED item in Supersedes: scan the delta spec I am about to write for any requirement that says "preserve X", "X MUST remain", or "backward compatibility with X". If found:

• Emit MUST_RESOLVE warning: "Spec includes a preservation requirement for '[X]' but proposal says '[X]' is REMOVED. Confirm intent."
• Pause for user confirmation before continuing.

3. For each REPLACED item in Supersedes: verify the spec describes the new replacement, not the old behavior. If spec only describes old behavior without acknowledging replacement, add a note: [PENDING: spec does not describe replacement behavior for [X] — clarify with design].

4. For CONTRADICTED items: verify the spec aligns with the resolution documented in ## Contradiction Resolution of the proposal. If mismatch, emit MUST_RESOLVE warning.

Step 2 — Identify affected domains

From the proposal I extract the domains that need specs:

• One domain = one coherent functional area (auth, payments, users, notifications, etc.)
• Each domain has its own spec file

Step 3 — Write delta specs

For each affected domain, I persist the delta spec (disk-primary, two steps, disk FIRST):

First write docs/sdd/{change-name}/spec.md with all domain specs concatenated, separated by ---. Then persist a pointer + summary keyed by sdd/{change-name}/spec (type architecture, scoped to the project), with content = "path: docs/sdd/{change-name}/spec.md\n\n{1-3 sentence summary}".

If the persistence layer is not reachable: still write the disk artifact (the source of truth); skip the pointer only.

Content format:

If NO existing spec — Full spec:

# Spec: [Domain]

Change: [change-name]
Date: [YYYY-MM-DD]

## Requirements

### Requirement: [Descriptive name]

Satisfies: [proposal scope item, e.g. S1]

[Description using RFC 2119 keywords]

#### Scenario: [Case name]

- **GIVEN** [precondition — system state]
- **WHEN** [action — what happens]
- **THEN** [observable result — what must happen]
- **AND** [additional result if applicable]

#### Scenario: [Edge case]

- **GIVEN** [...]
- **WHEN** [...]
- **THEN** [...]

If spec ALREADY EXISTS — Delta:

# Delta Spec: [Domain]

Change: [change-name]
Date: [YYYY-MM-DD]

## ADDED — New requirements

### Requirement: [Name]

Satisfies: [proposal scope item, e.g. S1]

[Description]

#### Scenario: [Name]

- **GIVEN** [...]
- **WHEN** [...]
- **THEN** [...]

## MODIFIED — Modified requirements

### Requirement: [Name of existing requirement]

Satisfies: [proposal scope item, e.g. S1]

[New description]
_(Before: [previous description])_

#### Scenario: [Name] _(modified)_

- **GIVEN** [...]
- **WHEN** [...]
- **THEN** [...]

## REMOVED — Removed requirements

### Requirement: [Name]

_(Reason: [why it is being removed])_

RFC 2119 Keywords (required)

Types of scenarios to cover

For each requirement I include:

1. Happy path: The normal, successful flow 2. Edge cases: Extreme values, empty lists, maximums 3. Error cases: What happens when something fails 4. Security cases: If applicable (authentication, authorization, permissions)

Examples of well-written scenarios

Well written

#### Scenario: Successful login with valid credentials
- GIVEN that the user exists with email "user@example.com" and the correct password
- WHEN they send POST /auth/login with those credentials
- THEN they receive status 200
- AND they receive a valid JWT in the "token" field
- AND the token expires in 24 hours

#### Scenario: Failed login with incorrect password
- GIVEN that the user exists with email "user@example.com"
- WHEN they send POST /auth/login with an incorrect password
- THEN they receive status 401
- AND the error message does NOT reveal whether the email exists

Poorly written (too vague)

#### Scenario: The user can log in
- GIVEN there is a user
- WHEN they log in
- THEN it works

Output Contract

{
  "status": "ok|warning|blocked",
  "summary": "Specs for [change-name]: [N] domains, [M] requirements, [K] scenarios.",
  "artifacts": ["docs/sdd/{change-name}/spec.md"],
  "next_recommended": ["sdd-tasks (after sdd-design)"],
  "risks": []
}

Rules

• Specs describe OBSERVABLE BEHAVIOR, not implementation
• Each requirement MUST have at least 1 scenario (happy path minimum)
• Scenarios MUST be testable and verifiable
• I do NOT include implementation details (that is sdd-design)
• I do NOT invent behavior — I base everything on the proposal and existing code
• If something is ambiguous in the proposal, I mark it as [Pending clarification] and list it in risks
• I do NOT add "preserve X" or "backward compatibility with X" requirements that are NOT explicitly stated in the proposal — if the proposal is silent, treat as pending clarification, NOT as implicit preservation
• If the proposal has no Supersedes section (archived change compatibility), I skip validation and proceed without error — backwards compat mode is non-blocking
• Every Requirement block MUST carry a Satisfies: line naming the proposal scope item it fulfills (e.g. Satisfies: S1). Coverage is bidirectional: every ### Included scope item in the proposal MUST map to at least one Requirement; every Satisfies: value MUST name a real scope item. A Requirement without Satisfies: is incomplete and MUST NOT advance to design.
• Normative keywords (MUST/MUST NOT/SHOULD/SHOULD NOT/MAY) MUST be UPPERCASE in requirement-description and THEN/AND lines. Lowercase must/should/may/shall in a normative position is non-normative prose and is REJECTED — a future hook greps \b(must|should|may|shall)\b in those lines.