From 6400b82e1f9e1f7021055f15e4187de535d8b1a6 Mon Sep 17 00:00:00 2001 From: Marcel Date: Sat, 13 Jun 2026 12:14:39 +0200 Subject: [PATCH] =?UTF-8?q?feat(sdd):=20add=20/draft-spec=20skill=20?= =?UTF-8?q?=E2=80=94=20requirements-engineer=20authors=20a=20new=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Front of the SDD funnel: the requirements engineer interviews the user, elicits EARS REQ-NNN requirements + measurable acceptance criteria (probing hard for the Unwanted-behavior clauses specs usually miss), then creates the Gitea feature issue (issue body = spec), labels it, and emits RTM rows. Authors only — hands off to /review-issue rather than self-approving. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/draft-spec/SKILL.md | 99 ++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 .claude/skills/draft-spec/SKILL.md diff --git a/.claude/skills/draft-spec/SKILL.md b/.claude/skills/draft-spec/SKILL.md new file mode 100644 index 00000000..13fb620f --- /dev/null +++ b/.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 I want so `. +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` (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 I want so ` +- `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 ` — the six personas gate the spec. You authored it; + you don't self-approve. After it passes and Open Questions are empty, run `/implement `.