---
name: spec
description: Write or update the specification under spec/ — the first phase of the Spec -> Build workflow.
argument-hint: Objective or planned feature
disable-model-invocation: true
---

Switch to **Spec mode** — the first phase of the Spec -> Build workflow.

Write inside `spec/` and `CLAUDE.md`. Everything else is read-only: investigate the implementation as far as it takes to keep the spec accurate — find inconsistencies, verify feasibility — and leave the code to `/build`.

The argument, when given, names the objective or the feature to spec.

## Find the Spec's Home

Most projects already keep specs, so the default is to update the document that already owns the topic, in place.

1. List `spec/` and read what is there. The layout on disk is the authority on where specs live and how they are named. Then read `CLAUDE.md` for the conventions the layout does not show.
2. Identify the document that owns the requirement. A feature change edits its own spec; a cross-cutting change like a rename edits every document it touches.
3. When nothing owns it, the change has no home — create one:

| Situation | Where |
| --- | --- |
| `spec/` is empty or absent | `spec/requirements.md` and `spec/design.md` |
| `spec/` already has a layout | a new directory following that layout, holding `requirements.md` and `design.md` |

The pair of filenames is fixed. The directory naming and depth belong to the repo — `spec/<domain>/`, `spec/features/<feature-name>/`, `spec/platforms/<x>/` are all fine; read the existing layout and match it. Follow [template.md](template.md) when creating a home.

An existing single-file spec stays a single file: update it in place rather than converting it.

## What Goes Where

Three routing tests, applied in order:

- **True of every feature in the repo** → `CLAUDE.md`, not the spec. Tech stack, commands, project structure, code style, the test framework and where tests live, and the Always / Ask first / Never boundaries all live there.
- **Still true after the implementation is thrown away and rewritten** → `requirements.md`. Observable behaviour, acceptance criteria, non-functional targets, and what the user sees when something fails.
- **Depends on the way it is built** → `design.md`. Architecture, components, data models, the mechanism behind a failure, and this feature's testing approach.

Violating a requirement makes the feature wrong; violating a design decision makes the code worse.

## Ask Where It Is Ambiguous

State the assumptions you are working from before writing anything:

```
ASSUMPTIONS:
1. ...
2. ...
→ Correct me now or I proceed with these.
```

Then batch the open questions into one round. Always ask:

1. The OBJECTIVE, target users (WHO), and the problem being solved (WHAT)
2. Observable behaviour and its acceptance criteria (HOW)

Ask these two only where `CLAUDE.md` does not already answer them; where it does, use what it says:

3. Constraints on the design — existing infrastructure, technology choices imposed from outside
4. Boundaries: what to always do, ask first about, and never do

Where `CLAUDE.md` is absent, write it from the answers: tech stack, commands, project structure, code style, testing conventions, boundaries. Where it exists, append only the conventions it is missing.

## Write the Spec

Read the target document(s) in full, then revise them against the new requirements, extending and reworking their existing sections rather than bolting on a parallel one.

Write acceptance criteria in EARS form (see [ears.md](ears.md) for the patterns), as a numbered list under each requirement. Turn a vague requirement into testable conditions rather than restating it:

```
"Make the dashboard faster"
→ WHEN the dashboard loads over a 4G connection THE SYSTEM SHALL reach LCP within 2.5 s.
→ WHEN a user opens the dashboard THE SYSTEM SHALL complete the initial data load within 500 ms.
```

Where the source only implies a criterion, record the gap under Open Questions instead of inventing one.

The spec is a living document: a changed decision lands here first and in the code second. Check the sibling specs for inconsistencies this change introduces and keep them coherent.

## Verify Before Finishing

1. `requirements.md` carries the objective and EARS acceptance criteria, and names no library, framework, or file path — unless the choice is a constraint imposed from outside.
2. `design.md` points at its `requirements.md` and states only behaviour that `requirements.md` already requires.
3. Every repo-wide convention sits in `CLAUDE.md` rather than in the spec.
4. `git status` shows changes under `spec/` and `CLAUDE.md` only.

Report what changed where, what you appended to `CLAUDE.md`, and what is still open. The user runs `/build` next, which breaks the spec into tasks and implements them.