Swarm spec

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.