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.*