| name | sdd-specify |
| description | This skill should be used when the user asks to "add a requirement / capability", "write or extend a spec", "make this behaviour normative (RFC-2119)", "record an ADR / architectural decision", or "resolve a STRAND". The SDD definition layer — authors the `REQ`, the canonical RFC-2119 `SPEC §`, and the `ADR`, assigning identifiers and wiring traceability. Not for exploring/design (superpowers brainstorming first); not for planning or building (superpowers writing-plans / executing-plans); a traceability audit (sdd-trace); or a one-line edit to an existing spec § (open the file directly). |
| argument-hint | <capability, behaviour, or decision to record> [REQ-id] |
| allowed-tools | Read, Write, Edit, Glob, Grep |
Specify — the SDD definition layer
Bundled references/ is at the plugin root (beside skills/, two levels above this file) — not under this skill. Read any references/… path as ${CLAUDE_PLUGIN_ROOT}/references/… on Claude Code, or ../../references/… from this skill's directory, or Glob for the installed references/… (host-agnostic).
Turn intent (often a design doc from superpowers:brainstorming) into the authoritative documents: a requirement (what + acceptance), the specification (how it must behave, RFC-2119), and an ADR when an irreversible decision is made. Read docs/.sdd.yaml first for identifier style and paths. Each artefact stays in its own file and lane — this skill bundles the authoring procedures, it does not merge the document kinds.
If the repo isn't scaffolded (docs/.sdd.yaml missing), route to sdd-scaffold. If the behaviour hasn't been explored yet, route to superpowers brainstorming first (see references/sdd-with-superpowers.md).
A · Requirement (REQ-*) — capture the capability
- Read
docs/.sdd.yaml for req_style, req_areas, req_gap.
- Assign the next identifier without collision — area-prefixed (
REQ-<AREA>-NNN, reject unknown areas) or flat-numeric (next slot at req_gap spacing).
- From
references/templates/requirement.md: capability (what + why), observable, testable acceptance criteria, explicit out-of-scope, and the two status fields (status: draft, implementation: proposed).
- Add the index row to
docs/requirements/README.md.
- No implementation detail — no file paths, no "how". Track the two status axes separately (
draft is binding now).
B · Specification (SPEC-* §) — make behaviour normative
- Open the canonical topic spec under
paths.specifications. Confirm no other file already owns this prose — never create a second copy.
- Look up ground truth for any domain fact in the source named in
.sdd.yaml (ground_truth); never guess.
- Write the statement with explicit RFC-2119 keywords (MUST/SHALL, SHOULD, MAY) and a stable
§N anchor. No task lists, no file paths, no PR summaries.
- Set/verify the
Status: header; wire the requirements index row to the canonical anchor (link only); add/update the traceability.yaml entry (references/traceability-schema.md).
- One canonical home — never duplicate normative prose. This is the cardinal rule.
C · ADR (ADR-NNNN) — record an irreversible decision
- Assign the next sequential number (never reused). From
references/templates/adr.md: Status (proposed → must be accepted before code depends on it), Context, Decision, Consequences.
- One decision per ADR. Long flows/DDL stay in the specs.
- Wire traceability: cite the
STRAND it resolves (and close that strand with a backlink) and the REQs it amends.
Working from a brainstorming design doc
A docs/superpowers/specs/*-design.md is input narrative, not the source of truth. Extract normative statements into the canonical spec (§B) and capture the capability as a REQ (§A). Redirect rules: references/sdd-with-superpowers.md.
Guardrails
- Keep the kinds separate even though one skill authors all three: a requirement has no normative prose, a spec has no tasks, an ADR holds one decision.
- Don't settle an open question silently — record it as an ADR (§C) or a
STRAND, or return to brainstorming.
- For a missing upstream capability (consuming a sibling SDD repo), see
references/cross-repo-gap.md.
- After specifying, hand off to superpowers planning per
references/sdd-with-superpowers.md (plan lands in docs/plans/ with the SDD citing header).
Reference
references/sdd-methodology.md — §3 document kinds & boundaries, §4 RFC-2119, §5 identifiers & single canonical home, §6 status axes.references/templates/{requirement,specification,adr}.md · references/traceability-schema.md · references/sdd-with-superpowers.md · references/cross-repo-gap.md.
