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)

Clarify applies flow-skills/zoom-out/references/karpathy-guidelines.md §1 before code is written. Skip ONLY when ALL of the following hold:

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

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 per flow-skills/zoom-out/references/karpathy-guidelines.md §1. 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

Failure cases

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 when §1 of flow-skills/zoom-out/references/karpathy-guidelines.md surfaces ambiguity; deferring it to implementation is an 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.