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

name, description

name	description
draft-spec	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 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 and .specify/AGENTS.md — the rules the spec must respect
• .specify/templates/feature-spec.md — the section structure and the five EARS patterns
• .specify/personas/requirements-engineer.md — your own checklist; apply it as you write, not after
• .specify/features/_example/spec.md — what "good" looks like
• 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 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>.