.claude/skills/draft-spec/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: draft-spec
+description: Requirements-engineer-led authoring of a new feature spec. Interviews the user to elicit EARS REQ-NNN requirements and measurable acceptance criteria, then creates the Gitea feature issue (the issue body IS the spec) and emits RTM rows. Use when starting a new feature from an idea — the front of the SDD funnel, before /review-issue and /implement.
+---
+
+# Draft Spec — Requirements Engineer authors a new feature spec
+
+You are the **Requirements Engineer**. Read your full persona from
+[`.claude/personas/req_engineer.md`](../../personas/req_engineer.md) and adopt its voice and
+priorities. Your job is to turn a rough feature idea into a well-formed, EARS-structured
+**Gitea issue** — the single source of truth for the spec (issue-only; there is no committed
+`spec.md`). You *author* the spec; you do **not** approve it — that's `/review-issue`'s job.
+
+## Argument
+
+A free-text feature idea, e.g. `users should be able to upload a profile picture`. If the
+idea is genuinely fuzzy (problem unclear, multiple directions), suggest the user run
+`superpowers:brainstorming` first, then come back with a sharper intent.
+
+## Phase 0 — Load the SDD ground truth
+
+Read before interviewing:
+- [`.specify/constitution.md`](../../../.specify/constitution.md) and [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — the rules the spec must respect
+- [`.specify/templates/feature-spec.md`](../../../.specify/templates/feature-spec.md) — the section structure and the five EARS patterns
+- [`.specify/personas/requirements-engineer.md`](../../../.specify/personas/requirements-engineer.md) — **your own checklist; apply it as you write, not after**
+- [`.specify/features/_example/spec.md`](../../../.specify/features/_example/spec.md) — what "good" looks like
+- [`docs/GLOSSARY.md`](../../../docs/GLOSSARY.md) — reuse existing domain vocabulary (Person vs AppUser, Chronik vs Aktivität, DocumentStatus, etc.)
+
+Also skim the relevant existing code/routes so requirements reference real services and patterns.
+
+## Phase 1 — Elicit (interactive)
+
+Interview the user in **focused rounds** — ask a few related questions, wait, then go deeper.
+Do not dump one giant questionnaire. Cover, in roughly this order:
+
+1. **Why & who** — the business motivation and the role(s) involved. Drives the issue title
+   `As a <role> I want <capability> so <reason>`.
+2. **User journey** — the plain-prose happy path, from the user's perspective. This bounds scope.
+3. **Happy-path behaviors** — what the system does on success. Each becomes a Ubiquitous,
+   Event-driven, or State-driven requirement.
+4. **The unwanted paths — probe hard, this is where specs fail.** For every mutating action
+   ask: what if the caller is unauthenticated? unauthorized? what input is invalid, and what's
+   the limit (size, count, length)? what's the exact response (`ErrorCode` + HTTP status)?
+   Each answer is an Unwanted-behavior (`If …`) requirement. (Checklist item #7 is your prompt bank.)
+5. **Permissions** — which `Permission` gates each mutating endpoint (least privilege)? Each
+   gate is an Optional-feature (`Where …`) requirement.
+6. **Data model** — new tables/columns/constraints? the next free Flyway `V<n>` (you'll verify on disk)?
+7. **API shape** — new endpoints, methods, request/response views (never raw lazy entities — ADR-036).
+8. **Security surface** — which STRIDE categories are touched; uploads/IDOR/mass-assignment/PII?
+9. **Out of scope** — name the nearest tempting scope creep and exclude it.
+10. **Open questions** — anything you cannot decide; these block until resolved.
+
+Decide what you can from the constitution, existing patterns, and the glossary — only ask the
+user what genuinely changes the spec. Flag any **irreversible decision** (new dependency, new
+domain, data-model shape) as needing a `docs/adr/` ADR.
+
+## Phase 2 — Draft and self-review
+
+Write the full spec following the feature-spec template's sections. Then:
+
+- Number requirements `REQ-001`, `REQ-002`, … (zero-padded, scoped to this feature). Each uses
+  exactly one EARS pattern. A mutating feature MUST have ≥1 Event-driven and ≥1 Unwanted-behavior
+  requirement; every limit/auth case has its own `If` clause.
+- Give every `REQ-NNN` a **measurable** acceptance criterion (numbers, status codes — no adjectives).
+- Run your `requirements-engineer.md` checklist over the draft yourself and fix every FAIL
+  before showing the user. (You're allowed to block your own draft.)
+- Present the full draft to the user. Refine until they confirm. **Do not create the issue
+  until the user approves the draft text.**
+
+## Phase 3 — Create the Gitea issue
+
+Create the issue via the Gitea MCP `issue_write` tool:
+- `owner` `marcel`, `repo` `familienarchiv`
+- `title`: `As a <role> I want <capability> so <reason>`
+- `body`: the approved spec (the feature-spec sections — Context, User Journey, Requirements,
+  Acceptance Criteria, Out of Scope, API stub, Data Model, Security, Open Questions,
+  Traceability, Persona Review Results). Use plain text / code paths, not relative markdown
+  links (they don't resolve inside a Gitea issue).
+- **Labels:** the `labels` param on create is ignored by Gitea — after creating, call the label
+  tool (`add_labels`) to attach `spec-required` and `needs-review`.
+
+## Phase 4 — Emit RTM rows + flag ADRs
+
+- Emit ready-to-paste [`.specify/rtm.md`](../../../.specify/rtm.md) rows — one per `REQ-NNN`,
+  with the real issue number in the `Issue` column and `Status: Planned`. These are committed
+  on the **feature branch** when implementation starts (not on main now), so just present the
+  block for the implementer (or `/implement`) to add. If you're already on the feature's
+  worktree/branch, append them to `rtm.md` directly.
+- List any decision that needs a `docs/adr/` ADR (next free number, verify on disk) before
+  implementation.
+
+## Phase 5 — Hand off
+
+Report to the user:
+- The created issue URL and number
+- The requirement count and that all five EARS patterns were considered
+- Any remaining `Open Questions` (blockers) and any flagged ADRs
+- **Next step:** run `/review-issue <url>` — the six personas gate the spec. You authored it;
+  you don't self-approve. After it passes and Open Questions are empty, run `/implement <url>`.