sdd:specify

Files (1)

• SKILL.md

SKILL.md (first lines)

## User Input

```text
$ARGUMENTS
```

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

---

## Shared Instructions

- [Transition Logging](../../lib/instructions/transition-logging.md) — append a transition entry on every `.spec-context.json` write
- [Branch Creation](../../lib/instructions/branch-creation.md) — optional feature-branch creation driven by `.sdd.json` `branchStage`
- [Layered Context](../../lib/instructions/layered-context.md) — 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.

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

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

```json
{ "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](../../lib/instructions/branch-creation.md).

Follow [branch-creation](../../lib/instructions/branch-creation.md) 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](../../lib/instructions/transition-logging.md).

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](../../lib/instructions/layered-context.md), 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):

```bash
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`:

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

Empty array if no domains matched. Append a transition entry per [transition-logging](../../lib/instructions/transition-logging.md).

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](../../lib/instructions/transition-logging.md).

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](../../lib/instructions/transition-logging.md).

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.

From alfredoperez/sdd, MIT.

More from alfredoperez/sdd