Spec

---
name: spec
description: Start or resume a specification for a change to this codebase. Interviews the user one question at a time, writes spec.md to disk, then separately lists the organizational policies the change touches. Use when the user asks to spec out a change, write requirements, plan a feature before coding, or says /brownspec:spec.
---

# Write a specification for a change

You are specifying **a change to an existing system**, not a greenfield project. The
system already has behavior, contracts, and consumers. Most of what you need is in the
repository — go read it before you ask the user anything.

## Phase 0 — Locate state

1. Read `.brownspec/conventions.md` and `.brownspec/project-map.json`. If either is
   missing, say once that `/brownspec:init` will produce them, then continue without.
   Rebuild the project map if the dependency manifest has changed since it was cached.
2. Read `.brownspec/policies.md` if present. **Do not apply it yet** — phase 3.
3. Derive the slug (kebab-case, from the user's description). Working directory is
   `.brownspec/features/<slug>/`.
4. If `spec.md` already exists there, **you are resuming.** Read it, find every
   `<!-- OPEN: ... -->` marker, and continue from the first one. Do not re-ask anything
   the file already answers.

## Phase 1 — Recon, then a draft

Run **levels 1 and 2** of the `repo-reading` skill. Establish:

- Which modules the change plausibly touches, and what they currently do
- The public contracts of those modules — HTTP/RPC, events, tables, config, CLI
- How similar changes were done before: `git log` on the touched paths, and any adjacent
  specs under `.brownspec/features/`
- Existing tests covering the affected behavior

**Do not run level 3 here.** Full blast radius is expensive and belongs in
`/brownspec:design`, once the change actually has a shape. What you need now is a
hypothesis about where it lands, not a complete dependency graph.

Then fill `${CLAUDE_PLUGIN_ROOT}/templates/spec.md.tmpl` with what you found and what
you can reasonably infer, and write it to disk. Inferences go in `Assumptions` marked
`(assumed)`. Anything you genuinely cannot infer gets an `<!-- OPEN: ... -->` marker in
place.

**The file on disk is the state of the interview.** Do not hold answers in your head.

## Phase 2 — Interview

Present the recon summary and your assumptions **first**. A wrong assumption is cheaper
for the user to correct than a question is to answer.

Then work through the `OPEN` markers.

- **One question per message.** Never batch. Never number a list of questions.
- **Only ask what changes the outcome.** If the answer would not change what gets built
  or how it is verified, record an assumption and move on.
- **Never ask what the repo can answer.** If you have not looked, look.
- **After every answer, rewrite `spec.md`** — replace the marker with resolved content,
  then ask the next question.
- Six questions or fewer. Past ten you are interrogating rather than specifying: write
  down what you have, move the rest to open risks, and stop.

Priority, highest first:

1. **Boundaries** — what is explicitly out of scope
2. **Behavior at the edges** — empty, duplicate, concurrent, oversized, unauthorized
3. **Failure** — what happens when each dependency is slow, down, or wrong
4. **Contract impact** — what breaks for existing consumers, and how they migrate
5. **Acceptance** — what observable fact proves this is done

## Phase 3 — Policy routing

**A separate pass, after the spec is otherwise finished.** Not woven into drafting — if
you apply policies while writing, you will shape the spec to satisfy them instead of
revealing where they bite.

Load the rules: every profile listed under `profiles:` in `.brownspec/policies.md`, read
from `${CLAUDE_PLUGIN_ROOT}/policies/<profile>.md`, plus the local rules in that file. If
nothing is enabled, write "No policies enabled" in the section and move on.

For each rule, match its **Trigger** against the finished spec. When it fires, add a line
naming the rule and **the specific decision or confirmation this spec still owes** — not
a restatement of the rule.

```markdown
## Policies touched

- **PDN-03** (logging of personal data) — needs a decision: where phone numbers are
  masked before they reach logs and traces
- **PDN-05** (retention) — needs confirmation: how long export files persist and what
  deletes them

Generated by matching policy triggers against this spec. **Not a compliance assessment.**
Requires review by whoever owns security.
```

Rules:

- **Route, never certify.** "Touches PDN-03, show security" — never "complies with
  152-ФЗ", "meets the requirement", or "no issues found". A false sense of coverage is
  worse than no check at all, because it stops someone from looking.
- Do not edit the body of the spec to make a rule stop firing. If the spec is genuinely
  wrong, say so and go back to phase 2.
- If a rule's trigger is ambiguous against this spec, list it as touched. Over-listing
  costs a reviewer a minute; under-listing costs an audit finding.

## Phase 4 — Exit check

Finished only when every item holds. State the result plainly; do not claim completion
while any fails.

- [ ] Non-goals are written and non-empty
- [ ] Every affected contract is named, with breaking changes flagged
- [ ] Behavior under dependency failure is specified
- [ ] Acceptance criteria are observable, and each maps to a stated requirement
- [ ] Every assumption is either confirmed by the user or listed as an open risk
- [ ] Nothing in the file merely restates what the code already shows
- [ ] Policy routing has run, and its output is a routing list — not a verdict
- [ ] Conflicts with `conventions.md` are written down with the reason for departing

Then say the spec is ready and that `/brownspec:design` is next. Do not design or write
code in this skill.

## What does not belong in a spec

Implementation detail the code will express better than prose — class names, function
signatures, chosen libraries, SQL. If a reader could learn it by opening the file, leave
it out. It will rot within a sprint and take the spec's credibility with it.