sdd-specify

name	sdd:specify
description	SDD — Spec-Driven Development: write a lean spec for rapid iteration.

User Input

$ARGUMENTS

If $ARGUMENTS is empty, stop and say: "Provide a feature description: /sdd:specify <description>"

---

Shared Instructions

• Transition Logging — append a transition entry on every .spec-context.json write
• Branch Creation — optional feature-branch creation driven by .sdd.json branchStage
• Layered Context — load Layer 1 living specs by domain (Step 3b)

Steps

1. Parse Input

Extract the feature description from $ARGUMENTS.

Generate a concise slug (2–4 words, action-noun format, lowercase, hyphens):

• "add clickable file references" → clickable-file-refs
• "fix payment timeout bug" → fix-payment-timeout
• Preserve technical terms (OAuth2, JWT, API)

Infer the conventional-commit type from the description. Used later by branch-creation.md (for the {type} variable in branchNameFormat) and by /sdd:implement commit-message generation.

Description starts with or mentions	type
"fix", "resolve", "repair", "bug", "broken", "regression"	fix
"refactor", "reorganize", "rename", "extract", "simplify", "cleanup"	refactor
"document", "docs", "readme"	docs
"chore", "bump", "upgrade dependency"	chore
anything else (default)	feat

---

2. Determine Spec Number + Create Directory

Scan specs/ locally for directories matching [0-9]+-*:

• Extract the highest number N found; use N+1 as the new number.
• If no spec dirs exist, start at 1.

mkdir -p specs/{NNN}-{slug}

Write specs/{NNN}-{slug}/.spec-context.json (first write — initialize transitions with from: null per transition-logging):

{ "workflow": "sdd", "currentStep": "specify", "currentTask": null, "progress": "parsing", "next": null, "updated": "{TODAY}", "selectedAt": "{ISO_TIMESTAMP}", "specName": "{Feature Name}", "branch": "{CURRENT_GIT_BRANCH}", "workingBranch": null, "type": "{feat|fix|refactor|docs|chore}", "createdAt": "{ISO_TIMESTAMP}", "transitions": [{ "step": "specify", "substep": "parsing", "from": null, "by": "sdd", "at": "{ISO_TIMESTAMP}" }] }

branch records the branch the user was on when /sdd:specify ran (audit trail). workingBranch is populated later if .sdd.json has branchStage set — see branch-creation.

Follow branch-creation with stage="specify". It is a no-op unless .sdd.json has branchStage: "specify".

---

3. Explore Inline

Update specs/{NNN}-{slug}/.spec-context.json — set progress to "exploring" and append a transition entry per transition-logging.

Without spawning a subagent, read 2–3 relevant files to understand the feature area:

• Run Glob and Grep searches in parallel (single message, multiple tool calls) to find files related to the feature description
• Read key sections to understand patterns, architecture, and constraints

---

3b. Load Layer 1 (Living Specs)

Per layered-context, determine which domains apply to the change by running the resolver script over the files surfaced by Step 3 (Glob/Grep hits + files you read):

python3 lib/scripts/resolve-spec-paths.py --changed <file>...

Load each matched domain's .spec.md in parallel, in the returned order (most-specific first — treat the leaf as primary context). The script handles location, membership, ordering, and the zero-config fallback; never hardcode .specs/<domain>/spec.md.

Record the result in specs/{NNN}-{slug}/.spec-context.json:

{ "loadedDomains": ["<domain>", "..."] }

Empty array if no domains matched. Append a transition entry per transition-logging.

If at least one domain matched, surface a callout in the Step 5 spec.md (see Step 5 below for the ## Modified Capabilities insertion). If none matched, this step is silent.

---

4. Detect Complexity

Update specs/{NNN}-{slug}/.spec-context.json — set progress to "detecting" and append a transition entry per transition-logging.

Based on what you found in Explore, classify the change:

Signal	Mode
Touches ≤3 existing files, change is <10 lines	minimal
Pure style or config tweak	minimal
Touches 4+ files, or adds a new component/service	normal
Introduces new public behavior or API	normal

If unclear, default to normal.

---

5. Write specs/{NNN}-{slug}/spec.md

Update specs/{NNN}-{slug}/.spec-context.json — set progress to "writing-spec" and append a transition entry per transition-logging.

Read lib/templates/spec-normal.md, fill placeholders ({Feature Name}, {NNN}, {slug}, {TODAY}), and write the result to specs/{NNN}-{slug}/spec.md.

If loadedDomains from Step 3b is non-empty, prepend a ## Modified Capabilities callout immediately after the Summary section, listing each domain as - **{domain}** — see .specs/{domain}/spec.md`` so reviewers know this change touches an existing capability spec. The author can later add ADDED / MODIFIED / REMOVED / RENAMED blocks (see lib/templates/spec-delta.md) — those blocks are what /sdd:implement syncs into Layer 1 at CP3.

Skip: clarification rounds, formal edge case analysis, exploration findings section, quality checklists.

---

6. Minimal Mode — Write plan.md + tasks.md

Skip this step if mode is normal.

Write specs/{NNN}-{slug}/plan.md:

Read lib/templates/plan.md, fill placeholders ({Feature Name}, {NNN}, {slug}, {TODAY}), simplify optional sections (omit Technical Context, Flow, Data Model, Risks — keep only Approach and a ## Files to Change list), and write to specs/{NNN}-{slug}/plan.md.

Write specs/{NNN}-{slug}/tasks.md:

Read lib/templates/tasks.md, fill placeholders ({Feature Name}, {TODAY}), keep only Phase 1 with the relevant tasks (omit Phase 2 for minimal changes), and write to specs/{NNN}-{slug}/tasks.md.

Update specs/{NNN}-{slug}/.spec-context.json — include step_summaries.specify and append a transition entry per transition-logging:

{
  "currentStep": "tasks",
  "currentTask": null,
  "progress": null,
  "next": "implement",
  "updated": "{TODAY}",
  "step_summaries": {
    "specify": {
      "complexity": "minimal",
      "requirements": N,
      "scenarios": N,
      "key_finding": "one-line summary of the most important codebase pattern discovered during exploration"
    }
  }
}

Where:

• complexity: "minimal" (since this is the minimal path)
• requirements: count of R### items in the spec.md just written
• scenarios: count of scenario sections (### headings under ## Scenarios) in spec.md
• key_finding: the most relevant codebase pattern or constraint discovered during Step 3 (Explore Inline)

---

7. Summary

Update specs/{NNN}-{slug}/.spec-context.json — set progress to null and append a transition entry per transition-logging. For normal mode, also set next to "plan" and include step_summaries.specify. For minimal mode, next is already "implement" from Step 6 (which already includes step_summaries.specify).

Normal mode .spec-context.json update:

{
  "currentStep": "specify",
  "currentTask": null,
  "progress": null,
  "next": "plan",
  "updated": "{TODAY}",
  "step_summaries": {
    "specify": {
      "complexity": "normal",
      "requirements": N,
      "scenarios": N,
      "key_finding": "one-line summary of the most important codebase pattern discovered during exploration"
    }
  }
}

Where:

• complexity: "normal" (since this is the normal path)
• requirements: count of R### items in the spec.md just written
• scenarios: count of scenario sections (### headings under ## Scenarios) in spec.md
• key_finding: the most relevant codebase pattern or constraint discovered during Step 3 (Explore Inline)

Read auto from specs/{NNN}-{slug}/.spec-context.json. If auto is true, use the (auto) variants below. Otherwise use the (manual) variants.

Minimal mode (manual) — display exactly this format:

⚡ **Spec ready — fast path**

{Feature Name} (`{NNN}-{slug}`)

Small change detected — generated spec, plan, and tasks in one shot.
{N} requirements · {N} tasks · {N} files to change

📂 spec · plan · tasks → `specs/{NNN}-{slug}/`

👉 Run `/sdd:implement {NNN}-{slug}` to start

Minimal mode (auto) — display exactly this format:

⚡ **Spec ready — fast path**

{Feature Name} (`{NNN}-{slug}`)

Small change detected — generated spec, plan, and tasks in one shot.
{N} requirements · {N} tasks · {N} files to change

📂 spec · plan · tasks → `specs/{NNN}-{slug}/`

🔄 Auto mode — continuing...

Normal mode (manual) — display exactly this format:

📋 **Spec ready**

{Feature Name} (`{NNN}-{slug}`)

{1-line summary from the spec's Summary section}
{N} requirements · {N} scenarios

📂 `specs/{NNN}-{slug}/spec.md`

👉 Run `/sdd:plan {NNN}-{slug}` to design the approach

Normal mode (auto) — display exactly this format. Note that no "continuing…" footer is shown: the orchestrator (/sdd:auto) displays the spec-review approval gate immediately after this skill returns, and a "continuing" footer would falsely suggest no user action is needed.

📋 **Spec ready** — orchestrator will gate for approval next

{Feature Name} (`{NNN}-{slug}`)

{1-line summary from the spec's Summary section}
{N} requirements · {N} scenarios

📂 `specs/{NNN}-{slug}/spec.md`