Requirements Specification

---
name: requirements-specification
description: Use when operator starts a new ticket ("ship X", "build Y", "add feature", "fix workflow") and no spec exists; produces spec, clarify questions, acceptance criteria. Do NOT use for code edits, mid-flight reorgs, or after a spec is locked.
source_inspiration: conceptual-only
license_status: clean-room-original
fusebase_flow_version: 2.1
risk_level: low
invocation: automatic
expected_outputs:
  - docs/specs/<slug>/spec.md
  - docs/specs/<slug>/clarify-conversation.md
related_workflows:
  - eight-phase-flow.md
  - session-initiation.md
hook_dependencies:
  - none
---

# Requirements Specification

## Purpose

Turn vague operator intent into a versioned spec with explicit acceptance criteria, unresolved clarify questions, and risk notes. The output is the contract every later skill (planning, implementation, validation, code review, security, deploy) reads.

## When to invoke

- Operator says "let's ship <feature>" / "build <feature>" / "add <feature>" / "fix <workflow>" / "we need <capability>"
- Backlog ticket exists at `docs/backlog/<slug>/README.md` and operator says "promote it"
- Active phase is `Specify` or `Clarify` (per FLOW_RULES state announcement)

## Do not invoke when

- A spec at `docs/specs/<slug>/spec.md` already exists and is scope-locked (decisions frozen; `decisions.md` shows **Lock status: LOCKED**) or its status is `DONE` (spec Status is DRAFT-until-DONE; scope-lock is a `decisions.md` flag, not a Status value)
- Operator is asking how something already works (use code-review or repo-onboarding-context-map instead)
- Task is a one-line bug fix that does not need clarify (see "Skip-clarify gate" below)

## Diagnosis, lane, and documentation-budget classification first (FR-21 + FR-23)

Before drafting a spec, allow bounded read-only diagnosis to identify the behavior, likely diff, and risk evidence. Run the changed paths through `hooks/local/lane-router.sh --json`, then inspect the diagnosed behavior/diff and declare every semantic risk trigger with evidence path/reason through `hooks/local/lane-assessment.py`. A mechanical match or semantic auth, permissions, secrets, data/schema, public-contract, production/release, protected-path, cross-cutting architecture, or unresolved product-decision trigger routes to **Full**. An initially unknown cause or file count alone does not. If assessment remains incomplete after bounded diagnosis, stop at `BLOCKED-AT-lane-assessment`; never infer a safe lane.

An ordinary, reversible, mechanically verifiable change with a complete no-trigger assessment is **Lightweight**: do not draft spec/clarify/decisions/tasks/gate. Record the one product outcome decision, router result, semantic declarations, proof, and rollback in a single **change-note** (`templates/change-note.md`) and route to `workflows/lightweight-lane.md` for one build→verify→deploy pass and a plain operator go-ahead. The skip-clarify gate below is a Full-lane micro-optimization.

Then run the FR-23 documentation-budget classifier (`flow-skills/documentation-budget/SKILL.md`) before creating any spec artifact: **Tier 0** (transient / already captured in code/tests/git) → no doc; **Tier 1** (Lightweight) → change-note only; **Tier 2** (mid-flight restart) → `docs/tmp/handoff.md` only; **Tier 3/4** → proceed to a full spec below. Do not create `docs/specs/<slug>/` artifacts for Tier 0/1/2 work.

## Skip-clarify gate (Full lane — when "skip clarify" is allowed)

The clarify phase exists to surface hidden ambiguity before code is written. Skipping it has a cost — undetected ambiguity surfaces later as wrong-direction code or operator-rework. Skip ONLY when ALL of the following hold:

| Skip condition | Concrete check |
|---|---|
| Single file, single function | Affects exactly one file; one named function or contiguous block |
| No new dependency / API / config | No `package.json`, no env var, no policy file change |
| Acceptance criterion fits in one sentence | "X now returns Y instead of Z" or equivalent |
| Operator typed "skip clarify" verbatim | Not inferred from "this is small" |
| No constitution-invariant question raised | Worker-undisturbed, mixed-fleet, auth gates all unaffected |

If ANY condition is unmet: run clarify, even if the operator pushes for speed. The phrase "the spec for a small fix is two paragraphs" applies (per `docs/operator-discipline.md` OD-6).

When skipping: spec.md is still drafted and its scope is frozen in the same step (spec `Status: DRAFT` — scope-lock is recorded in `decisions.md` (**Lock status: LOCKED**), NOT as a `Status: LOCKED` value; the Status stays DRAFT until the deploy session flips it to DONE). The clarify-conversation.md file is replaced by a one-line note: `Clarify skipped per operator request; ticket meets skip-clarify gate (see requirements-specification/SKILL.md).`

## Full-lane Phase 1 / Phase 2 split (diagnostic vs fix)

Use this split only after an objective trigger has already selected Full and implementation acceptance still depends on deeper diagnosis:

**Phase 1 — Diagnostic.** Acceptance criterion is "we can name the root cause + cite evidence". No production code change. Output: an investigation note in `docs/specs/<slug>/diagnostic.md` with reproduction steps, suspected component, and evidence (logs, traces, repro). The phase ends when the operator confirms the diagnosis.

**Phase 2 — Fix.** Drafted as a separate spec section (or separate spec file `<slug>-fix/spec.md`) AFTER Phase 1 closes. Acceptance criteria are concrete code changes; verification gate references the diagnostic.

Do not use this split merely because the cause was unknown at intake. Ordinary lane diagnosis happens before persistent spec artifacts. If that bounded diagnosis resolves the behavior without an objective Full trigger, route to Lightweight. If lane assessment remains incomplete, stop at `BLOCKED-AT-lane-assessment`.

## Required inputs

| Input | Where it lives | If missing |
|---|---|---|
| Backlog ticket or operator intent | `docs/backlog/<slug>/README.md` or chat | Ask operator for one-liner + why-now + rough scope |
| Constitution / project context | `FLOW_RULES.md` + project-specific values in `AGENTS.md` | Stop and ask operator to fill `AGENTS.md` project-specific section |
| CLI edition map, for Fusebase Apps work | `docs/fusebase-cli-edition.md` | Continue with Flow-only spec, but mark CLI domain assumptions unknown |
| Letter prefix in use | Project-specific section of `AGENTS.md` | Default to `A`; ask operator to confirm |

## Procedure

1. Read the backlog ticket (or capture operator intent in chat as a 1-paragraph problem statement).
2. Perform bounded read-only diagnosis when cause or risk is unclear. Persist the router result and semantic declarations. Route complete no-trigger ordinary work to the Lightweight change-note; route objective triggers to Full; unresolved assessment stops at `BLOCKED-AT-lane-assessment`.
3. For Fusebase Apps tickets, read `docs/fusebase-cli-edition.md` and identify any CLI domain skills that should inform scope, constraints, or acceptance criteria. Use them as supporting context; do not copy their content into the spec.
4. Identify ambiguities. For each, draft a clarify question with 2–3 options + recommendation. Save to `docs/specs/<slug>/clarify-conversation.md` using `templates/clarify-conversation.md`.
5. If the operator asks for alternatives, variations, product/UI directions, or other possible shapes, invoke `flow-skills/design-discovery-ideation/SKILL.md` before drafting the final clarify options. Capture the selected direction in `clarify-conversation.md` or `spec.md`.
6. Present clarify questions in chat text (FR-19): no popup / clickable menu tools. Use a short options table or numbered list when there are multiple choices, with **(Recommended)** marked when appropriate.
7. Wait for operator answers. Update `clarify-conversation.md` with locked answers.
8. Draft `docs/specs/<slug>/spec.md` using `templates/spec.md`. Status: DRAFT.
9. Spec must include: problem statement, why-now, in-scope, out-of-scope, acceptance criteria (numbered AC1..ACn), risks, constraints from FLOW_RULES (worker-undisturbed, mixed-fleet if applicable). **For app-feature tickets — quality-pattern scan:** check the category index in `flow-skills/app-quality-patterns/SKILL.md`; every pattern whose Trigger matches this feature becomes an AC citing its ID (e.g., "AC4 — filter/report state encoded in URL; refresh restores the exact view (QP-01)"). Cite IDs only — do not paste pattern bodies (FR-23). **For audience-classified surfaces** (`docs/audience.md` exists — or the operator explicitly requested a client-vs-internal posture check — and `client-vs-internal` classified the surface): each applicable posture checklist row becomes an AC citing its C/I/S ID (e.g., "AC7 — destructive actions confirm before executing (client-vs-internal C2)"); where a row overlaps a QP pattern, cite both IDs on one AC line.
10. State announcement footer in chat: phase advances from `Specify` to `Plan` once spec.md is saved.

## Worked example

A reported formatting defect has no known cause. Bounded read-only diagnosis finds one reversible formatter change; the path router has no match and semantic assessment is complete with no trigger. Write one change-note with the product outcome decision and use the Lightweight pass. If the same diagnosis finds an access-control branch, declare `auth` with its source path and reason, then continue here with a Full spec.

## Output artifacts

| Artifact | Path | Mode |
|---|---|---|
| Spec | `docs/specs/<slug>/spec.md` | Mode B (full) |
| Clarify conversation | `docs/specs/<slug>/clarify-conversation.md` | Mode B (full) |
| Backlog index update (if promoted) | `docs/backlog/index.md` | Mode B (full) |

## Failure cases

| Failure mode | Detection | Response |
|---|---|---|
| Operator can't answer clarify question | After 1 round, operator says "I don't know" | Park spec at `BLOCKED` status; file follow-up backlog ticket for the unknown |
| Backlog ticket conflicts with FLOW_RULES invariant | Constitution check fails | Stop. Ask operator to revise scope OR amend project-specific rules. Don't proceed silently. |
| Scope is actually two tickets | Spec needs >12 acceptance criteria, multiple deploys, or splits naturally | Stop. Propose splitting into `<slug>-a` and `<slug>-b` backlog tickets. |
| Investigation reveals the ticket is wrong | During clarify, evidence shows the reported behavior is intentional, the bug is elsewhere, or the feature already exists | **Abort the ticket.** Mark spec status `ABORTED` with one paragraph: what was investigated, what was found, why no work follows. Move ticket back to `docs/backlog/<slug>/README.md` with status `aborted-on-investigation` so it doesn't reappear. Do NOT silently downscope to "fix the wrong thing instead." |
| Operator and clarify keep disagreeing on scope | After 2 rounds of clarify, the gap between operator's intent and what the spec captures is widening | Stop. Switch to a 1:1 clarify-only chat: ask the operator to restate the goal in 3 sentences. If the gap persists, escalate to architect (`workflows/architect-escalation.md`) — the framing problem is bigger than spec drafting can resolve. |

## Escalation path

- Investigation surface > 10 files across multiple subsystems → propose architect escalation via `workflows/architect-escalation.md`
- Operator asks for divergent product/UI/workflow alternatives → invoke `design-discovery-ideation` before locking the spec direction
- Operator can't decide between two architectural directions → invoke `implementation-planning` skill in "decision-only" mode to surface trade-offs

## Anti-patterns

- Do not draft `decisions.md` here — that's `implementation-planning`'s job
- Do not draft `tasks.md` here — same
- Do not write production code (FR-01)
- Do not lock the spec on operator's behalf (FR-11) — operator confirms by saying "lock spec" or "redirect AC<n>"
- Do not skip the clarify phase if ambiguities exist; "I'll figure it out during implementation" is FR-11 violation

## Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See `docs/source-map.md`.