specify

Files (4)

• README.md
• SKILL.md
• reviewer-prompt.md · references/
• visual-companion.md · references/

SKILL.md (first lines)

# Specify

Turn approved intent into a lintable, testable SpecScore Feature.

## Hard Gate

<HARD-GATE>
Do NOT invoke `writing-plans`, `frontend-design`, `mcp-builder`, or ANY implementation skill until ALL of the following are true:
  1. The Feature artifact exists at `spec/features/<slug>/README.md` and contains at least one `#### REQ: <slug>` requirement inside the `## Behavior` section.
  2. Each requirement has ≥1 acceptance criterion in `Given / When / Then` format.
  3. `specscore spec lint` passes.
  4. The reviewer gate has released — every entry in `gates.specify.reviewers` (including the `type: human` entry that captures the user's approval) returned `Approved` per the [reviewer-gates](../../spec/features/reviewer-gates/README.md) Feature's AND-composition.

This applies to **every** Feature, regardless of perceived simplicity. The only skills invoked after `specstudio:specify` are `writing-plans` (Plan) or `specstudio:implement` (Implement), as chosen by the user at the transition menu.
</HARD-GATE>

## When to Use

- A SpecScore Idea is `Approved` and ready to become a Feature.
- User has a clear, high-conviction buildable intent (may skip `specstudio:ideate`).
- Behavior of an existing Feature needs to change — **revise in place** (see [path-conventions.md](../shared/path-conventions.md)).

## Anti-Pattern: "This Is Too Simple To Need A Spec"

Every Feature goes through this. A toggle, a one-line config, a single utility — all of them. Simple Features are where unexamined assumptions cost the most. The spec can be short (a few sentences for truly simple Features), but it **must** be written and approved.

## Pre-Flight

1. **Inputs check.** If triggered from an approved Idea, load it and list the Idea's assumptions that this Feature must validate. If no Idea exists, ask: "Is this ready to specify, or should we ideate first?" — don't force `specstudio:ideate` on high-conviction users.
2. **Scope decomposition.** If the intent spans multiple independent subsystems, stop and help the user decompose into multiple Features before continuing.
3. **Revision vs new.** If a Feature with this slug already exists, decide: revise in place (default) or create a successor and set `**Supersedes:** <old-slug>` in the new Feature's body metadata (only when scope change invalidates existing ACs). See [path-conventions.md](../shared/path-conventions.md).

## Checklist

Create a task for each and complete in order:

1. **Explore project context** — existing Features, recent commits, related specs.
2. **Scope decomposition check.**
3. **Offer visual companion** (if visual questions are ahead) — own message, no other content. See [visual-companion.md](references/visual-companion.md) (still TBD — see [the analysis doc §11.1](../../spec/research/ideate-vs-brainstorming-skills-analysis.md)).
4. **Ask clarifying questions** — one at a time, multiple-choice preferred. See [question-cadence.md](../shared/question-cadence.md).
5. **Propose 2–3 approaches** with trade-offs; lead with your recommendation. Use `specstudio:ideate` lenses (inversion, constraint removal, simplification) where useful.
6. **Present spec sections** one at a time, get approval after each.
7. **Create the Feature artifact** — run `specscore feature new <slug>` (the required-CLI creation path; see `## Artifact Creation`), then FILL the scaffolded sections (REQs, ACs, etc.) via `Edit`. Topics group under `### <Topic>` headings inside `## Behavior`, each containing one or more `#### REQ: <slug>` requirements.
8. **Rehearse stub decision** — per-AC heuristic. See [rehearse-heuristic.md](../shared/rehearse-heuristic.md).
9. **Lint** — `specscore spec lint`.
10. **Inline self-review** — placeholders, consistency, scope, ambiguity.
11. **Run the reviewer gate** — load and dispatch `gates.specify.reviewers` from `specscore.yaml` per the [Reviewer Gates](../../spec/features/reviewer-gates/README.md) Feature. See the `## Reviewer Gate` section below.
12. **Publication + events** — maintain a checkpoint manifest for the Feature README, optional `_tests/`, assets, indexes, and CLI-reported touched paths. Apply [publication-policy.md](../shared/publication-policy.md) for `feature.specified` after lint passes and before reviewer-gate dispatch, then emit `feature.specified` with `publication_result`. After the reviewer gate releases, apply policy for `feature.approved`, then emit `feature.approved` (carrying the released `grade` and `publication_result`) and write the `**Grade:**` body-metadata line per Step 4. See [events.md](../shared/events.md).
13. **Transition** — present the transition menu (see `## Transition`).
14. **Throughout** — watch for sidekick ideas per [sidekick-capture.md](../shared/sidekick-capture.md). When an out-of-scope improvement surfaces, invoke `specstudio:sidekick` with a one-liner, acknowledge in one line, and return to the current checklist step immediately. Do not derail to discuss the sideline idea.

## Spec Sections (scale to complexity)

- **Purpose & user job** — from the Idea's HMW if applicable, or restated here.
- **Requirements** — numbered, each with ≥1 acceptance criterion.
- **Architecture & components** — isolation, interfaces, dependencies. Each unit: what does it do, how is it used, what does it depend on?
- **Data flow.**
- **Error handling & failure modes.**
- **Testing strategy** — references Rehearse stubs (or explains why none).
- **Not Doing / Out of Scope** — inherited from Idea + spec-level cuts.
- **Assumption carryover** — which Idea assumptions survive; which are now invalidated or answered.

## Artifact Layout

A Feature is a single `README.md` (plus optional `_tests/` and `assets/`):

```
spec/features/<slug>/
├── README.md                # The Feature artifact (single file)
├── _tests/                  # Optional — Rehearse scenarios (see shared/rehearse-heuristic.md)
│   ├── <scenario-1>.md
│   └── …
└── assets/                  # Optional — diagrams, mockups
```

The skill carries **no embedded schema** — `specscore feature new` is the single source of truth for the Feature's structure (title prefix, body metadata, `## Behavior` / `#### REQ:` / `## Acceptance Criteria` sections). For a read-only spec reference, see [`https://specscore.md/feature-specification`](https://specscore.md/feature-specification) — never fetch it to write the file; the CLI scaffold produces the canonical structure.

## Artifact Creation

**Creation is required-CLI.** `specscore feature new <slug>` is the ONLY way to create the Feature artifact — it produces a lint-clean skeleton by construction and updates the features index for you. There is **no direct-write fallback**: the CLI scaffold is the single source of truth for the Feature's structure. This follows the Required-CLI Artifact Creation policy — see the **Creation-class row** in [`../shared/cli-detection.md`](../shared/cli-detection.md).

### Step 1 — Run the creation call and branch on exit status

Do **not** run a standalone `command -v` probe. Invoke `specscore feature new <slug>` (passing the fields you already have) and branch on its exit status per the **Creation-class row** in [`../shared/cli-detection.md`](../shared/cli-detection.md) (which carries the per-outcome rationale): **`0`** → scaffold written, continue to Step 2; **`127`** → install message (`/specscore:install`), then **install-then-retry**; **exit `8`** → **upgrade-then-retry**, naming the missing `feature new` subcommand; **any other non-zero** → surface verbatim, **never** a direct-write fallback.

### Step 2 — Fill the scaffolded sections

With the lint-clean skeleton in place, FILL its sections via `Edit`: the `## Summary`, `## Problem`, `## Behavior` topics with their `#### REQ: <slug>` rules, and the `## Acceptance Criteria` in `Given / When / Then` form. Preserve the scaffold's lint-clean structure — never replace it with a hand-authored layout.

## Acceptance Criterion Format

Every AC uses `Given / When / Then`. This is **enforced by lint rule F-004**.

```
Scenario: <short name>
Given <precondition that sets state>
When <action the system or user takes>
Then <observable outcome that can be checked>
```

If you can't phrase an outcome as `Then <observable>`, the AC is too abstract — sharpen it.

## Rehearse Stub Decision

After drafting ACs, for each one apply the heuristic in [rehearse-heuristic.md](../shared/rehearse-heuristic.md):

- **Testable** (has CLI/HTTP/pure-fn/data/UI-selector/fs/event surface): scaffold `spec/features/<slug>/_tests/<req-slug>-<ac-slug>.md` with `**Status:** pending` body metadata.
- **Not testable** (subjective, abstract, undefined observer, doc-only Feature): skip; record reason in the Feature's `README.md` under `## Rehearse Integration`.

The user can always override the heuristic.

## Inline Self-Review

Check:

1. **Placeholder scan** — `TBD`, `TODO`, incomplete sections, vague requirements.
2. **Internal consistency** — architecture matches feature descriptions; requirements align with ACs.
3. **Scope check** — focused enough for one implementation plan? If not, decompose.
4. **Ambiguity check** — could any requirement be interpreted two ways? Pick one; make it explicit.

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills