---
name: saf-create-spec
description: Create or update a repository-local, evidence-based SDD specification package from a requested outcome or existing code; use project config when present and effective defaults otherwise.
compatibility: Requires Git and a compatible Agent Skills host.
---

# Create SDD Specifications

## When to use

Use when a feature, change, bug fix, or technical initiative needs an implementation-ready SDD
specification package — whether it starts from a requested outcome (**source-item mode**) or from
code that already exists in the repository with no prior spec and no requested outcome to start from
(**existing-code mode**). Read [spec
lifecycle](../sdd-agentic-flow-shared/references/spec-lifecycle.md) for new vs same slug, optional
`Lifecycle:` / `Extends:` / `Supersedes:`, and the do-not-glob rule.

## When not to use

Do not use for direct implementation, a casual explanation, or an unscoped brainstorming request.

## Inputs

- **Source-item mode:** the requested outcome and known constraints.
- **Existing-code mode:** an explicit **scope** — the specific module, feature, package, directory,
  or bounded area to reverse-engineer, named by the user. Never proceed against an unstated or
  whole-repository scope — ask the user to name a bounded area first.
- `.sdd-agentic-flow/config.yml`, when present; otherwise canonical effective defaults.
- Relevant repository evidence: code, tests, existing decisions, and prior SDD artifacts (within the
  stated scope, in existing-code mode).
- A converged `discovery.md` or `brief.md`, when present for the named feature workspace.

## Workflow

1. Determine the mode. If the user provides a requested outcome, ticket, or feature request, use
   **source-item mode**. If the user asks to document or formalize behavior that already exists in
   the code with no prior spec and no requested outcome, use **existing-code mode** and confirm the
   user has named an explicit scope — a specific module, feature, or bounded area, not the whole
   repository — before continuing; ask for one if it is missing or too broad.
2. Read `.sdd-agentic-flow/config.yml` when present and use its overrides; otherwise use the
   canonical effective defaults.
3. Read `../sdd-agentic-flow-shared/references/tlc-baseline.md` to apply the common lifecycle and
   required decision points. Read `../sdd-agentic-flow-shared/references/feature-profiles.md` and
   resolve the profile for this work package: a physically present valid `workflow.feature_profile`
   is an `explicit-override`; otherwise infer from the current request and repository evidence and
   record `inferred`. Do not treat an effective built-in `medium_feature` fallback as an override.
   Read `../sdd-agentic-flow-shared/references/work-types.md`. Infer **work intent** (`feature` /
   `bugfix` / `refactor` / `investigation` / `maintenance`) from the request or source item and
   state it in prose near the top of `spec.md` or `context.md` (example: `Work intent: bugfix`).
   Work intent is not a config key, not a CLI `--type`, and not a fifth `feature_profile`. Apply the
   matching content contract from `work-types.md` inside existing headers — do not add `## Unchanged
   behavior` or `## System Invariants`, and do not create `bugfix.md`.

   The persisted context fields are normative: `Feature profile: <canonical-token>`,
   `Feature profile source: inferred|explicit-override`, and `Profile rationale: <concise reason>`.
   Only this skill classifies or reassesses the profile; downstream skills consume the persisted
   value and must not re-infer it.
4. Read `../sdd-agentic-flow-shared/references/task-slicing.md`,
   `../sdd-agentic-flow-shared/references/artifact-contracts.md`,
   `../sdd-agentic-flow-shared/references/workflow-safety.md`, and
   `../sdd-agentic-flow-shared/references/spec-lifecycle.md` before handling inputs or writing
   artifacts. New slug → new folder. Same slug → identify overwrite and wait for an explicit update
   request (already in Safety). If the work extends or supersedes another package, record canonical
   `Extends:` / `Supersedes:` in `context.md`. Optional `Lifecycle: draft` or `active` in
   `context.md` (not a new H2). Do not glob sibling `spec.md` files except to detect slug collision
   or an explicit relation. Read `../sdd-agentic-flow-shared/references/engineering-principles.md`
   so `design.md` follows existing architecture. If the existing architecture is flawed, record the
   tension; in autonomous mode, reconcile an intent-preserving correction through this canonical
   writer when repository evidence supports it; do not silently change acceptance semantics.
5. Read `.sdd-agentic-flow/context/project-context.md` when it exists; treat it as read-only
   discovered output. In source-item mode, also read `.sdd-agentic-flow/context/domain-glossary.md`
   when it exists; propose or create it only with explicit authorization and a source or uncertainty
   note for every term. When a converged discovery artifact exists, read only its relevant decisions
   and findings, then re-ground them against current repository evidence. `discovery.md` informs the
   package; `spec.md` becomes the normative requirement authority.
6. Inspect the evidence, applying `../sdd-agentic-flow-shared/references/evidence-standard.md`:
   - **Source-item mode:** inspect only evidence needed to state the current behavior, desired
     behavior, constraints, risks, and acceptance criteria. Mark unknowns as open questions rather
     than inventing facts.
   - **Existing-code mode:** inspect the named code, its tests, and its call sites within the
     confirmed scope. Classify every finding as **Observed** (directly shown by code or a passing
     test), **Inferred** (a reasonable reading of the code that no test directly confirms), or
     **Unknown** (a gap neither the code nor its tests answer). Never present an Inferred or Unknown
     finding as Observed.
7. Create the artifacts:
   Apply `../sdd-agentic-flow-shared/references/evidence-standard.md#requirement-coverage` when
   shaping obligations: separate independently verifiable outcomes, account for enumerated members,
   and identify proof obligations for negative guarantees within the existing profile and headers.
   - **Source-item mode:** create exactly `context.md`, `spec.md`, `design.md`, and `tasks.md`;
     never create `validation.md`. Keep requirements traceable to evidence, give each acceptance
     criterion an **observable expected outcome** (status, code, persisted state, or invariant), and
     slice code tasks vertically where practical. Criteria may carry `AC-*` IDs and `Examples:`
     (prose first; assumption ≠ criterion; forbidden-outcome example) per
     `../sdd-agentic-flow-shared/references/artifact-contracts.md#acceptance-criterion-identity`
     and `#acceptance-discovery-and-examples`. Optional invariant sentences live **inside**
     existing requirement/AC text (`INV-…` allowed). Do not add a required `## Invariants` header.
     When work intent is **bugfix** (any `feature_profile`, not only `small_fix`), include current
     broken behavior, a **reproduction sensor** that fails on current code, expected fixed behavior,
     **unchanged behavior** with regression sensors, root cause, and fix boundary — still inside
     existing headers.
   - **Existing-code mode:** create exactly `context.md`, `spec.md`, and `design.md`, labeling every
     requirement and decision Observed, Inferred, or Unknown; only create `tasks.md` if the user
     confirms follow-up work is needed. Never create `validation.md`.
8. **Scope and spec analysis**: before drafting a large package, determine whether the request
   contains several independently testable capabilities. If it does, record a lightweight capability
   map and dependency direction in the existing context/brief artifacts, then specify bounded
   capabilities rather than disguising several features as one task graph. After drafting
   requirements and **before** treating the spec as ready, inspect the set for ambiguity (divergent
   implementations), contradiction (collectively impossible), unstated assumptions, missing edge
   cases / failure modes, unverifiable acceptance criteria, and impacted modules / call sites (from
   the same inspection already used for evidence — not a mandatory `git grep` ritual). For each
   relevant consumer surface — interface, consumer, persistence, configuration, authorization,
   failure mode, or state transition — record an observable criterion, observed behavior with a
   source reference, an `N/A` rationale, or an open question inside existing artifacts. This
   extends, and does not replace, Observed/Inferred/Unknown (existing-code) and
   Known/Assumed/Unknown (brainstorm). Skip this pass **only** when `feature_profile` is `small_fix`
   **and** the work is well-understood; record the skip in the spec or output so it is not silent.
   Do not present a skip as if analysis ran. No 15th skill; no Analyze CLI.
9. **SPEC-Q completion gate** (v4): before treating the package implementation-ready, verify
   SPEC-Q1–SPEC-Q11 — critical requirements observable; no unresolved consequential ambiguity;
   observable acceptance criteria; explicit scope/review boundary; explicit task dependencies;
   identifiable contractual seams/sensors; reconciled applicable invariants; no material
   spec/design/tasks contradiction; intentional optional-artifact omissions; task completion
   criteria evidence-backed or deterministically derivable; known consequential human-judgment
   boundaries explicit. Structural facts (headers, REQ-* IDs, unique `AC-*` IDs with a valid
   parent `REQ-*`, resolvable dependencies, acyclic task graph, requirement anchors) may be checked
   deterministically; semantic sufficiency remains an
   explicit skill/human decision.
10. Check internal links, paths, and consistency with existing artifacts. In source-item mode,
    summarize unresolved decisions. In existing-code mode, summarize Observed behavior, Inferred
    behavior, Unknown/open questions, and any gaps between observed behavior and observed tests, so
    the user can confirm or correct each Inferred and Unknown item before it is relied on. In
    autonomous mode, resolve evidence-backed, intent-preserving ambiguity through this canonical
    writer; surface only underdetermined intent or authority expansion.

## Safety

- Do not use private conversation context as specification evidence or copy secrets into artifacts.
- Do not access networks, install dependencies, or modify application code, infrastructure, or
  defaults.
- Preserve existing artifacts unless the user explicitly requests an update or an authorized
  autonomous intent-preserving reconciliation permits the update; identify any overwrite before it
  occurs.
- In existing-code mode, never present Inferred or Unknown findings as Observed, confirmed
  requirements; label every finding Observed, Inferred, or Unknown.
- Apply `../sdd-agentic-flow-shared/references/workflow-safety.md` for data handling and
  confirmation requirements.

## Output

Return the created or updated artifact paths, evidence consulted, and: in source-item mode, a
concise scope and acceptance-criteria summary plus open questions or decisions required before
implementation; in existing-code mode, a concise summary of findings labeled Observed, Inferred, or
Unknown, so the reader can distinguish confirmed behavior from inference and unresolved gaps at a
glance. Include `Status`, `Next recommended skill`, and `Reason`.

### Autonomy

Supports `manual`, `supervised`, and `autonomous` autonomy levels. In `autonomous` mode, advancing
to
`saf-create-prompts` or `saf-implement` requires `spec.md` and `design.md` with no unresolved
Unknown blocking an acceptance criterion. Evidence-backed intent-preserving reconciliation may
continue through this canonical writer; underdetermined intent or authority expansion returns
control to the human. See `../sdd-agentic-flow-shared/references/autonomy-guardrails.md`.