---
name: write-spec
description: Write a full feature spec — user stories, acceptance criteria, edge cases. Pass a feature name or PROJ-X ID.
argument-hint: "feature name or PROJ-X"
user-invocable: true
---

# Write Spec

You are a product manager turning one feature idea into a complete, testable
specification. No code, no technical decisions — that is `/architecture`'s job.

## Grill Me principle

- **One question at a time** — never a list
- **Always offer a recommended answer**
- **Follow the conversation**, resolve dependencies between decisions as they surface
- **Read the codebase before asking** anything it can answer
- **No question limit** — stop when you understand the feature

## Before starting

1. Read `docs/PRD.md` and `features/INDEX.md`
2. `git ls-files src/components/ src/app/api/`

**If the PRD is still the empty template:**
> "Das Projekt ist noch nicht aufgesetzt. Führe erst `/init` aus." → Stop.

**If no argument:** list all features with status Roadmap and ask which one.

## Three entry points

| Situation | What to do |
|-----------|------------|
| Status **Roadmap** in INDEX.md | Go straight to the interview |
| **Not in INDEX.md** | Clarify name, priority (with a recommendation) and dependencies, add it with the next PROJ-X ID and status Roadmap, then interview |
| Status **Planned** or higher | "PROJ-X hat schon eine Spec. Nutze `/refine PROJ-X`." → Stop |

## Interview

Start from the PRD and the INDEX entry. First question targets the biggest open
point about this specific feature. Cover through conversation:

- Who exactly uses it (refer to the PRD's user types)
- The core action — the job to be done
- What success looks like from the user's side
- Must-have behaviour for the MVP
- Validation rules and limits
- Error states: what happens when things go wrong
- Empty states: what the user sees before any data exists
- Edge cases: concurrent edits, network failure, invalid input, permission boundaries
- Dependencies on other features (auth, data)
- Performance or security requirements

Be concrete about edge cases: "Was passiert, wenn zwei Nutzer denselben Datensatz
gleichzeitig bearbeiten?" beats "Gibt es Randfälle?"

## Write the spec

Use `template.md`. Save to `features/PROJ-X-feature-name.md` (kebab-case).
**German**, per the project language rule.

Three sections carry the memory of this interview — do not skip them:

- **Out of Scope** — everything discussed and consciously excluded, referencing
  other features by ID ("Massenlöschen — verschoben auf PROJ-5"). Without it,
  developers do not know what *not* to build.
- **Produkt-Entscheidungen** — every scoping and UX decision with its rationale
- **Offene Fragen** — anything unresolved, as `- [ ]` so it stays visible

Present the draft, apply feedback, then save.

## Acceptance criteria format

German, Angenommen/Wenn/Dann — one testable statement per line:

```
- [ ] Angenommen [Vorbedingung], wenn [Aktion], dann [Ergebnis]
```

Examples:
- [ ] Angenommen der Nutzer ist angemeldet, wenn er ein leeres Formular abschickt, dann erscheint pro Pflichtfeld eine Validierungsmeldung
- [ ] Angenommen eine Aufgabe existiert, wenn der Nutzer auf „Löschen" klickt, dann erscheint erst ein Bestätigungsdialog
- [ ] Angenommen die API antwortet nicht, wenn der Nutzer speichert, dann wird eine Fehlermeldung gezeigt und die Eingabe bleibt erhalten

Each one must be directly testable by `/qa` without interpretation.

## Granularity (Single Responsibility)

One spec = one testable, deployable unit. Split when it targets a different user
role, a different screen, or can be tested and shipped on its own. Never combine
CRUD for different entities, or user plus admin functions.

Document dependencies explicitly:
```markdown
## Abhängigkeiten
- Benötigt PROJ-1 (Auth-Grundlage) — für die Prüfung auf angemeldete Nutzer
```

## After saving

- `features/INDEX.md`: status Roadmap → **Planned** (and next ID if newly added)
- `docs/PRD.md`: update the roadmap status column if the feature is listed there
- Re-read both to verify

## Wrap up

- [ ] 3–5 user stories
- [ ] Out of Scope filled in with references
- [ ] Every criterion in Angenommen/Wenn/Dann form
- [ ] Produkt-Entscheidungen logged with rationale
- [ ] Offene Fragen logged
- [ ] 3–5 edge cases documented
- [ ] Saved as `features/PROJ-X-feature-name.md`
- [ ] INDEX.md and PRD updated and verified
- [ ] User approved

## Handoff

> "Spec steht. Nächster Schritt: `/architecture` für das technische Design von PROJ-X."

## Commit

```
feat(PROJ-X): Write feature specification for [feature name]
```