/swarm-spec

name: swarm-spec
description: Requirements phase — a clarifying, options-first stakeholder interview that removes confusion and assumptions (not a relentless grilling) and produces a validated SRS + per-feature specs with EARS acceptance criteria and ISO 25010 NFRs. Use to start a new project's requirements, gather/analyze/specify/validate requirements, stress-test a plan, or mine requirements from an existing codebase (brownfield). Also handles requirement changes after validation.

swarm-spec — requirements phase

Quality here is leverage: every later phase builds on this document. Expect the strongest available model — if this session runs a lesser tier, say so and let the user decide.

Pick a planning mode first

Requirements work isn't an interrogation — the goal is to **remove confusion and unstated assumptions**, not to make the user answer a hundred questions. Before diving in, offer how much to involve them (recommend **hybrid**; they can switch anytime):

• **ask-each** — put every genuinely uncertain requirement to the user before locking it.

Maximum control, slowest.

• **recommend-all** — proceed on your recommendations/assumptions for *all* features, record

each assumption, and surface them together for one batch review. Fastest.

• **hybrid** *(default)* — ask on the high-stakes or truly ambiguous decisions; assume sensible

defaults on the rest and log them. The user may also scope it ("ask me about auth and billing, assume the rest").

Whatever the mode, **every assumption is recorded** (in the question queue, status `ASSUMED`) so the closing summary can show exactly what you decided for them.

Clarify, don't grill

Only *decisions* go to the user; *facts* are looked up (codebase, vault, web). For each decision surfaced: **lead with a recommendation**, state the assumption behind it, list the alternatives, and accept any free-text answer. If something is only mildly uncertain and the mode allows, assume the sensible default and note it rather than asking.

**The question queue** — `30 Plans/<P>/question-queue.md` (machine lane) — keeps a long conversation honest across sessions and compaction:

• Every item gets an ID + status: `OPEN / ASKED / ANSWERED / ASSUMED / PARTIAL / PARKED`.
• An answer that resolves other items: cross-mark them with the answer's ID.
• The user changes topic or adds a requirement mid-stream: APPEND a new branch; the main track

is never dropped. Return to open items before the phase can complete.

• Re-read the queue on resume — it, not the transcript, is the memory.

Probe the quality dimensions explicitly, even unprompted (offer defaults so this stays light): performance, security, usability, reliability (ISO 25010: functional suitability, performance efficiency, compatibility, usability, reliability, security, maintainability, portability). Ask about interfaces (Web/Mobile/Desktop/TUI/CLI/none), stakeholders, constraints (budget, stack, compliance), and what is explicitly OUT of scope.

Brownfield mode (existing code)

Mine first, ask second — the repo is a stakeholder whose answers are already written down. Reverse-engineer requirements from README/docs/tests/code into specs marked `status: mined-draft`, each statement carrying provenance (`file:line`). Present for batch validation; interview only gaps, conflicts, and low-confidence items. Never re-ask what the sources answer.

Outputs (human lane, in repo `docs/`, mirrored to vault `30 Plans/`)

• **`docs/SRS.md`** — vision, stakeholders, scope in/out, constraints, FR index with

MoSCoW priorities, NFRs in EARS notation, traceability scheme, build milestones, changelog, glossary.

• **`docs/specs/FR-XX-<slug>.md`** per feature — story, details, acceptance criteria

(EARS), edge cases, `requires:` dependencies. Template: `90 Templates/spec.md`.

EARS patterns: ubiquitous ("The X shall…"), event ("WHEN … shall…"), state ("WHILE …"), unwanted ("IF … THEN …"), optional ("WHERE …"). Every FR: unique ID, priority, ≥1 testable criterion, edge cases considered.

Validation gate (ends the phase)

Don't make the user read the whole SRS to approve it. First present a **review summary** they can skim in a minute, then point them at the full doc for anything they want to drill into:

• **What we're building** — one plain-language paragraph.
• **Features** — each FR as one line: `FR-07 — resume any project from cold state (Must)`.
• **Key decisions** — the choices that shape the build (stack, interfaces, scope boundaries).
• **Assumptions I made for you** — every `ASSUMED` item, so a wrong guess is easy to catch.
• **Explicitly out of scope** — so silence isn't mistaken for agreement.
• **Open questions** — anything still `OPEN/PARKED`.

Invite a quick "OK" or targeted changes. On approval, flip `status: draft → validated`. Then ask the **mode question**: gated (user verifies each milestone) or auto (sweeps self-verify, no stops) — record in flow-state along with `phase: design`.

Changes after validation (requirements management)

New/changed requirement → tracker entry + SRS changelog + version bump + propagate to every artifact that mentions it (specs, design, tickets) via FR-ID references. Flag impacted downstream work; never edit silently.

--- *Influences: Pocock's grilling & to-spec; superpowers brainstorming; Jeffallan's feature-forge & spec-miner; ISO 25010; EARS; workingsoftware.dev NFR guide — see CREDITS.md.*