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)

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 § Promote: Read and copy rich content into memory-bank phase 2 and/or story ARCH|SEC|ANALYSIS before synthesizing the PRD. Prefer promoted siblings and memory-bank over re-asking. Pointer-only citations are not Prior context.

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 (those folders are required, not optional). 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 STOP: If FEATURE needs_* is true (or brownfield) and the story lacks the matching ANALYSIS/ / ARCH/ / SEC/ folder/files: STOP. Do not Write PRD. Return to O1 (/orchestrate-analyze) or create those folders first. 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 (include /features/; keep /PRD/ /PLAN/ as safety net only; do not add /memory-bank/ — commit bank when product knowledge; never commit secrets). 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. 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.
5. 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):

.\scripts\validation\validate-prd.ps1 -Path <written-prd-path>

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

.\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. Handoff with portable feature path (STORAGE.md § Portable path):

/sdd-plan - features/NNN-slug/US01/PRD/NNN_short_feature_slug.md

(Global: 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
• Write PRD when flag-gated required siblings (ANALYSIS/ / ARCH/ / SEC/) are missing for true FEATURE needs_* / brownfield — STOP; max-3 gap questions do not replace this gate
• 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 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

Handoff

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