Template
Florian Wilde
b0c4e9e9b9
Toolchain fixes (all previously broken): - npm run lint: next lint was removed in Next 16 -> eslint with flat config - .eslintrc.json was ignored by ESLint 9 -> eslint.config.mjs - npm test / test:e2e exited 1 with no tests -> passWithNoTests - Vitest scanned tests/ and would have run Playwright specs -> scoped to src/ - Playwright targeted Mobile Safari while docs installed only chromium - reuseExistingServer silently tested a foreign server on :3000 -> E2E_PORT - 11 high-severity vulns -> npm audit fix - deny rule Read(**/.env*) also blocked .env.example -> precise patterns Stack changes: - Tailwind v3 -> v4 (CSS-first, no tailwind.config.ts, tw-animate-css) - shadcn regenerated for v4; 33 components -> 6 core, bundled radix-ui - Supabase removed entirely; data layer is now chosen per project - Vercel removed; Docker Compose self-hosting with scripts/update.sh - Better Auth + passkey plugin as the binding auth standard - ThemeProvider and Sonner mounted; dark mode and toasts now actually work Workflow system: - Sub-agents wired: /frontend, /backend, /qa delegate to .claude/agents - Checklists folded into their SKILL.md; one file per skill - Rules rewritten: DB-agnostic backend, passkey security, v4 frontend - Spec language settled as German, skill instructions English
127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
---
|
||
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]
|
||
```
|