Writes delta specifications with requirements and Given/When/Then scenarios.

/sdd-spec <change-name>

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

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).

• The proposal artifact (the WHAT and WHY):

  • mem_search(query: "sdd/{change-name}/proposal")

    →

    mem_get_observation(id)

    for full content.
  • If not found and Engram not reachable: proposal content passed inline from orchestrator.

• ai-context/architecture.md

  if it exists (to understand the current system)

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.

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

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

• GIVEN [...]
• WHEN [...]
• THEN [...]

undefined

• GIVEN [...]
• WHEN [...]
• THEN [...]

• GIVEN [...]
• WHEN [...]
• THEN [...]

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)

• 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

• 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

undefined

• GIVEN there is a user
• WHEN they log in
• THEN it works

---

• 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