Sdd Spec

---
name: sdd-spec
description: Create a PRD for a new feature or change (agent PRD .md; language per LANGUAGE.md + preferences under features/). Feeds sdd-plan. Use when creating a spec or invoking /sdd-spec.
---

## STOP - Read before ANY tool call

1. Read `{{GUARDRAILS_PATH}}`
2. Read `_shared/sdd-artifacts/SESSION.md`; load session-state for `$Cwd`
3. If the relevant gate is not approved: **STOP** - ask user **(pt-BR)** - do **NOT** Write/Shell
4. SDD/develop skills: after **ONE** step/task, **STOP** session - handoff only
5. This skill body is **English**; user-facing prompts may be **(pt-BR)**

### Step -1 - Gate check (report in chat before continuing)

```
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] PIPELINE.md read (SDD skills only)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
```

---

# Skill: sdd-spec

## Trigger

Invoke when the user asks for: `/sdd-spec`, `create spec`, `new feature`.

## Outcome

A complete **PRD** (agent `.md` artifact) in the **user chat language** (or `preferences.json` / manifest `artifact_language` when set) at a **canonical** path under `features/NNN-slug/USnn/PRD/` (Classic SDD default story `US01`; or `TSnn`). Global: `{{SDD_ROOT}}/<repo-id>/features/...`. Root/flat `PRD/` is **not** a valid Classic SDD path. Include **## Execution policy** from `templates/sdd/PRD.md`. Mandatory input for **sdd-plan**.

## PRD boundaries

The PRD answers **what**, not **how**. No implementation code. Identifiers (types, APIs, paths) in **English**.

## Lazy-load (only when needed)

| When | Path (after sync) |
|------|-------------------|
| Command playbook (step discovery after gates) | `{{TOOLKIT_ROOT}}/skills/sdd-spec/references/command.md` |
| Pipeline guards, modes, confirm, paths | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/PIPELINE.md` |
| Storage, manifest, `.gitignore` | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE.md` |
| Invocation contexts (`direct` vs `orchestrated`, `IC-DIRECT-ORCHESTRATED`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/INVOCATION-CONTEXTS.md` |
| Contract provenance (`agreed` vs `invented`, `CP-AGREED-VS-INVENTED`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/CONTRACT-PROVENANCE.md` |
| Selective retrieval (`SR-NO-FULL-DUMP`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/SELECTIVE-RETRIEVAL.md` |
| CHANGE brownfield / current specs (`CHANGE-CONTRACT`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/CHANGE-CONTRACT.md` |
| PRD document template | `{{TOOLKIT_ROOT}}/skills/_shared/templates/sdd/PRD.md` |
| Caveman Mode (if active) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md` - **Lite cap** |
| SDD artifact language | `{{TOOLKIT_ROOT}}/rules/sdd-artifact-language-pt-br.mdc` |
| Language surfaces (chat vs spawn) | `{{TOOLKIT_ROOT}}/skills/_shared/agents/LANGUAGE.md` |
| .NET / C# context | `dotnet-guidelines/clean-architecture.md`, `csharp-patterns.md` |
| Reference index (routing only) | `{{TOOLKIT_ROOT}}/skills/sdd-spec/reference.md` |
| Process step detail (lazy) | `{{TOOLKIT_ROOT}}/skills/sdd-spec/references/<section>.md` |
| Context pressure | `{{TOOLKIT_ROOT}}/rules/context-management.mdc` |
| Product depth challenge (Step 5.5) | `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/feature-altitude.md`, `invest-and-story-quality.md`, `gherkin-budget.md`, `clarify-depth.md`, `product-evidence-lite.md` |
| Anti-task-shatter titles (only if task-shaped) | `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/anti-task-shatter.md` |

**Never by default:** do not preload `references/command.md` before Step -1 gates; do not preload all `references/*.md`, full sdd-plan/develop packs, all templates, or all `backlog-item-types/*`. Contract first (`PIPELINE` + `STORAGE`); after gates load `references/command.md` for step discovery; load **one** `references/<section>.md` per Process step (`SKILL-REFERENCE-RETRIEVAL.md`). Load Product-depth norms only at Step 5.5 (or when FEATURE/STORY siblings are thin).

## Process

After gates: **Read `references/command.md`** for ordered step discovery (prefer over dumping this Process into prompts). Then load `references/<section>.md` for authoring tables — **not** full `reference.md`.

### Step -1b - Caveman Mode (Lite cap)
1. Read `{{SDD_ROOT}}/preferences.json` (create `{ "caveman_mode": false, "caveman_level": "full", "orchestrator_mode": "always", "artifact_language": null }` if missing).
2. If `caveman_mode` is false: continue without compression.
3. If true: load `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md`; apply **Lite** participation cap + prefs `caveman_level` (Lite skills never escalate); show once: `[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.`
4. Honor `caveman on|off|status|lite|full|ultra` (and `stop caveman` / `normal mode`) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per `CAVEMAN.md`.

### -1. Pipeline and mode

Load `STORAGE.md` and `PIPELINE.md`. Use `STORAGE.md` schema v2 and run the dynamic storage resolution algorithm with parameter `$Workflow = classic`. Resolve `storage_mode` and `path` for the active repository. If this is the first run for the repository, execute the storage mode selection flow and persist it in `manifest.json`.
Resolve `invocation_context` per `INVOCATION-CONTEXTS.md` (`IC-DIRECT-ORCHESTRATED`): default `direct` unless parent handoff marks `orchestrated`. Apply the matching observable table.
Load `CONTRACT-PROVENANCE.md` (`CP-AGREED-VS-INVENTED`): distinguish `agreed` vs `invented` on every REQ/CA/assumption while authoring; never present invented as agreed (TE02).
Apply Phase A/B: in Plan/Ask, draft in chat only until Agent + user **sim** on section Confirm below. Pipeline lock: no PLAN, no `Edit`/`Write` on `*.cs`, `*.csproj`, migrations.

### 0. Workspace

Target repo (not this toolkit repo unless subject). Read `AGENTS.md` / `README.md`. Detect stack. Resolve `<repo-id>` and classic feature root (`STORAGE.md`). Glob PRDs under `features/**/PRD/` only (workspace + global feature root) for `NNN`. Classic SDD default story folder = `US01` when unspecified.

### 1. Requirements

**Prior context** (chat, code-review, backlog, **feature siblings**, **promoted bank**): structured summary + max **3** gap questions - skip full questionnaire (`PIPELINE.md` section Prior context + Feature / story siblings). Apply **selective retrieval** (`SELECTIVE-RETRIEVAL.md`, rule `SR-NO-FULL-DUMP`): **must not** dump entire `memory-bank/` or paste a full PRD into prompts/handoffs — paths + short summaries only.

**Resolve-PRD / cited `.md`:** If the user cited a non-feature `.md` (including `.cursor/plans/`), follow `PIPELINE.md` § **Classic PRD/PLAN promote** (`invocation_context=direct`): **Read** → synthesize PRD → confirm → `Write` under `features/.../PRD/`. Do **not** require `orchestrate-analyze` first. Prefer **promoted siblings and memory-bank** over re-asking.

When under `features/NNN-slug/`, load `FEATURE.md`, `CONTINUITY.md`, `STORY.md`, `REFINE/` when present (optional / on demand), and `ANALYSIS|ARCH|SEC` when the matching FEATURE `needs_*` (or brownfield) is true. Prefer sibling/bank content over re-asking; still max **3** gap questions. Bank reads = named files only (never recurse-load the whole tree into context).

**Required siblings (`IC-DIRECT-ORCHESTRATED`):** Resolve `invocation_context` at skill start (`INVOCATION-CONTEXTS.md`).
- **`direct`:** if no `FEATURE.md` with `needs_*` → do not require siblings. If flags exist and folders missing → ask (create inline / proceed at operator risk / optional `/orchestrate-analyze`); do **not** hard-block.
- **`orchestrated`:** if FEATURE `needs_*` (or brownfield) and matching `ANALYSIS/` / `ARCH/` / `SEC/` missing → **STOP**; return to O1. Max-3 gap questions do **not** replace this gate.

**Otherwise** ask (pt-BR):

```
Vou criar o PRD. Informe:
1) Feature - o que construir ou alterar?
2) Comportamento atual
3) Comportamento esperado
4) Contexto adicional (opcional)
5) ID de rastreamento — **fortemente recomendado** usar IDs estáveis `REQ-NNN` (três dígitos); se o usuário citar issue/US externa, mapear para REQ no PRD
```

Wait for answers.

### 2-5. Confirm repo, explore code, clarify (<=5), technical analysis

Per existing skill intent: branch confirmation, Glob/Grep/Read, brief impact/risks for the PRD. Capture **blast radius** when multiple areas change.

### 5.5 Challenge vagueness + product depth + REQ contract

Before drafting: challenge vague goals/AC ("works correctly", "as expected", "funciona corretamente"). Require observable outcomes. Assign stable **REQ-NNN** IDs (required — at least one; strongly recommended for every functional behavior) mapped to CA; list explicit **OOS**; use **EARS** only when hybrid clarity helps (not universal). Details: `references/challenge-vagueness.md`, `references/req-tracking.md`, `templates/sdd/PRD.md`.

**Product depth (lazy):** challenge FEATURE/STORY siblings and the PRD draft for mandatory depth — FEATURE Problem/Goals/Non-goals/Evidence; STORY Objective + Who/Job/Outcome (US) + AC budget happy/rule/failure; PRD **metrics**, **MoSCoW**, open questions with **Severity**. Cite norms via portable paths; ask what/outcome gaps only — **no how, no implementation code**. Load backlog norms from the Lazy-load table only in this step.

Apply `CP-AGREED-VS-INVENTED`: operator answers and cited Prior context → `agreed`; agent defaults / inferences → `invented` (Assumptions / open questions) until confirm. Invented must stay visibly labeled in the draft and must not be written as locked requirements.

### 6. Context checkpoint

`context-management.mdc`. At >=40%, draft in chat or partial file; warn before continuing.

### 6.75 Confirm before write

Show title, `NNN`, **portable canonical path** (`STORAGE.md` § Portable path; confirm chat may also show resolved OS absolute), storage mode, bullets (incl. REQ-NNN count / OOS), remaining **`invented`** assumptions (if any), and status **Pronto para planejamento**. Wait for **sim** / **ajustar** / **cancelar**. In Plan/Ask without **sim** in Agent: Phase A message only. On **sim**, listed bullets in that confirm become `agreed` for the Write (`CONTRACT-PROVENANCE.md`).

Record `artifact_language` from `preferences.json`, manifest, or user override (`LANGUAGE.md` — do not hard-code pt-BR).

### 7. Write PRD (Agent + sim only)

1. Validate path per `PIPELINE.md` section Path validation - abort if non-canonical (**writes** only under `features/.../PRD/`).
2. Repository mode: `.gitignore` per `STORAGE.md` and `features_versioned` in manifest (`references/storage-gitignore.md`). Global mode: do **not** edit `.gitignore`.
3. Path: `features/NNN-slug/US01/PRD/NNN_short_feature_slug.md` (adjust story id); body from `templates/sdd/PRD.md` (authoring: `references/template-usage.md`, `references/filename-numbering.md`, `references/storage-gitignore.md`); include **## Execution policy**.
4. **Navigation `## Related` (REQ-009 / CA3):** Emit `## Related` per `STORAGE.md` § Navigation block (`NAV-RELATED` / `NAV-OMIT-ABSENT`). Classic: cite **PLAN** when the canonical PLAN path is known/on-disk (omit if absent — never stub PLAN only for a link); cite **STORY** / FEATURE / CONTINUITY / ARCH… only when on-disk. Paths portable only. Details: `references/template-usage.md`.
5. **Brownfield CHANGE (REQ-004):** If FEATURE `Nature` is `brownfield` (or sibling FEATURE under `features/NNN-slug/` says brownfield), also Write `features/NNN-slug/CHANGE.md` from `templates/features/CHANGE.md` with **ADDED \| MODIFIED \| REMOVED** vs **current** (`memory-bank/` living docs — never `openspec/` / `.specs/` / `.specify/`). **Greenfield** must **not** force an empty CHANGE stub. Details: `CHANGE-CONTRACT.md` + `references/validate-change.md`.
6. Product `docs/` in scope: ask doc language first (`references/product-docs-language.md`).

### 7.5 Structural validate before advance

After a successful `Write`, run structural **`validate-prd`** (no LLM) before handoff (`references/validate-prd.md`):

```
pwsh -NoProfile -File "{{TOOLKIT_ROOT}}/scripts/validation/validate-prd.ps1" -Path <written-prd-path>
```

When `CHANGE.md` was written (brownfield), also run:

```
pwsh -NoProfile -File "{{TOOLKIT_ROOT}}/scripts/validation/validate-change.ps1" -Path <features/NNN-slug/CHANGE.md>
```

(Toolkit consumers: same script names under the synced InstallRoot validation folder when present.) Exit ≠ 0 → **STOP**; fix REQ-IDs / CA headings / CHANGE sections; re-run until exit 0. Do **not** advance to `/sdd-plan` on failure. Enforcement smoke: `Assert-ValidatePrdPlan.ps1`, `Assert-ChangeContract.ps1`.

Report path, storage, language, `.gitignore` changes. After `validate-prd` (and `validate-change` when brownfield) exit 0, run `refine-story/references/tech.md` § Story PRD contestation on the written PRD. An open question stops with `open_question`. Do not hand off to plan or checklist. When contestation finds no open question, hand off with portable paths:

```text
/split-story-checklist - features/NNN-slug/US01/STORY.md
/sdd-plan - features/NNN-slug/US01/PRD/NNN_short_feature_slug.md
```

Skip the checklist line when FEATURE complexity is `trivial`. Orchestrated O2 runs the same contestation and then the checklist before `sdd-plan` without leaving the feature. Global paths use `sdd/<repo-id>/features/...`.

## Must not

- Hard-code PRD body to pt-BR when user chat is another language; implementation code in PRD
- `Write` outside canonical feature PRD folders (never root/flat `PRD/`); skip confirm-before-write
- Hard-block PRD in `orchestrated` context when flag-gated siblings are missing; in `direct` context, ask instead of blocking (`INVOCATION-CONTEXTS.md`)
- `Edit`/`Write` production or test code; create PLAN in this session
- Claim "PRD saved" without successful `Write`
- External trackers; do not paste full guideline bodies into PRD
- Do not dump entire `memory-bank/` or paste full PRD into prompts/handoffs (`SELECTIVE-RETRIEVAL.md` / `SR-NO-FULL-DUMP`)
- Do not ignore `IC-DIRECT-ORCHESTRATED` — resolve and apply `direct` vs `orchestrated` (`INVOCATION-CONTEXTS.md`)
- Do not ignore `CP-AGREED-VS-INVENTED` — never present `invented` content as `agreed` (`CONTRACT-PROVENANCE.md` / TE02)
- Do not ship vague CA/REQ without challenge; do not omit REQ-IDs or OOS from the PRD body
- Do not ship a PRD missing metrics (§1.3), MoSCoW (§4.3), or Severity on remaining open questions (§5.1) without challenging depth first (`references/challenge-vagueness.md`)
- Do not put implementation how/code into the PRD while challenging product depth
- Do not hand off to `sdd-plan` or `split-story-checklist` while PRD contestation still has an open question, or when `validate-prd` exits ≠ 0
- Do not hand off when brownfield lacks `features/NNN-slug/CHANGE.md` or `validate-change` exits ≠ 0; do not invent empty CHANGE for greenfield
- Write SDD artifacts containing OS absolute paths matching `^[A-Za-z]:/` or user-home InstallRoot embeds (`…/.cursor/sdd/…`, `…/.claude/sdd/…`) — use portable paths per `STORAGE.md` § Portable path
- Omit `## Related` on PRD Write, use `## See also`, stub absent siblings only for links, or embed non-portable paths in Related (`STORAGE.md` § Navigation block / REQ-009)

## Handoff

```
/sdd-plan - <portable-prd-path-under-features>
```

Run Story PRD contestation before that handoff. An open question replaces the handoff with `open_question`. When the feature is medium or complex, hand `/split-story-checklist - <portable-story-path>` first.