/requirements-authoring-flow

name: requirements-authoring-flow
description: "Workflow for authoring requirements and specifications: drafting, review, validation, etc."
tags: ["workflow"]
baseSchema: docs/schemas/workflow.md

<requirements-flow>

<description_and_purpose> Prevents premature drafting by enforcing HITL gates where every `<req>` unit receives explicit user approval before proceeding. Each phase produces traceable artifacts (Final Requirements Set, Validation Pack, Traceability Matrix). Input: user request for new requirements, edits, review, refactor, or validation; USE SKILL `requirements-authoring` and PROACTIVELY REQUIRE its use in all phases and subagents. </description_and_purpose>

<workflow_phases>

<prerequisites phase="0", applies="ALL">

1. All Rosetta prep steps MUST be FULLY completed 2. USE SKILL `load-project-context`, `hitl` 3. MUST ALWAYS use todo tasks ledger, ASAP. Phases are sequential. Independent tasks can run in parallel. 3. No rush, take your time, MUST FOLLOW WORKFLOW ENTIRELY, no skipping 4. Every phase MUST update `requirements-authoring-flow-state.md` in FEATURE TEMP with: phase name, status, artifact produced, and open questions. 5. Orchestrator and subagents MUST USE SKILL `requirements-authoring`. 6. If task is to reverse engineer orchestrator MUST USE SKILL `reverse-engineering`. 7. Keep requirement identifiers in code comments only, must not be user facing. 8. If `/goal` is set repeat phases 5-6 until goal is met, then continue with the rest of phases. 9. This workflow MUST be used with Fable, Opus, GPT-5.5+ class models => IF NOT - DEMAND USER TO SWITCH MODEL

IMPORTANT! If the task is to reverse engineer requirements, spawn MULTIPLE subagents with each handling one unit of analysis (one screen, one page, one controller, one endpoint, etc) to effectively prevent hallucinations by narrow scoping for phases intent_capture, outline, draft, validate.

</prerequisites>

<discovery phase="1" priority="must" subagent="discoverer" role="Context analyst collecting project and scope signals" subagent_required_model="claude-sonnet-5, gpt-5.4-medium, gemini-3.1-pro, grok-4.5, gpt-5.6-terra">

Artifact: Discovery Summary (context, existing requirements, constraints, affected files). Done when: scope boundaries and relevant requirement files are identified.

1. Complete all Rosetta prep steps 2. Detect environment and project structure 3. Read existing requirements, glossary, assumptions, constraints 4. Identify requirement areas (FR, NFR, interfaces, data, traceability) 5. Record assumptions and unknowns 6. Required skills: `requirements-authoring` 7. Recommended skills: `reverse-engineering`

</discovery>

<research phase="2" priority="should" subagent="requirements-engineer" role="Researcher collecting standards and prior decisions" subagent_required_model="claude-opus-4-8, gpt-5.5-high, gemini-3.1-pro-high, gpt-5.6-sol">

Artifact: Research Notes (sources, constraints, prior art, reusable requirement patterns). Done when: relevant references are gathered OR no additional sources are needed. Skip when: local context is complete and no external standards are needed.

1. Gather supporting docs and prior decisions 2. Collect requirement patterns and quality criteria 3. Capture measurable thresholds and terminology constraints 4. Required skills: `requirements-authoring`

</research>

<intent_capture phase="3" priority="must" subagent="requirements-engineer" role="Requirements analyst capturing intent and assumptions" subagent_required_model="claude-opus-4-8, gpt-5.5-high, gemini-3.1-pro-high, gpt-5.6-sol">

Artifact: Intent Capture. Done when: intent is restated, scope and goals confirmed, assumptions listed, and questions resolved.

1. Restate intent and confirm scope and goals 2. List assumptions and targeted questions 3. HITL: present intent capture and get explicit approval 4. Resolve blockers before outlining or drafting 5. Required skills: `requirements-authoring`

</intent_capture>

<outline phase="4" priority="must" subagent="requirements-engineer" role="Information architect proposing MECE requirement layout" subagent_required_model="claude-opus-4-8, gpt-5.5-high, gemini-3.1-pro-high, gpt-5.6-sol">

Artifact: Requirement Outline (areas, file mapping, ID strategy, traceability plan). Done when: user approves structure and requirement batching strategy.

1. Propose MECE structure and area abbreviations 2. Map files and IDs without writing final requirement text 3. HITL: get user approval on structure and scope 4. Required skills: `requirements-authoring`

</outline>

<draft phase="5" priority="must" subagent="requirements-engineer" role="Author drafting atomic requirement units" subagent_required_model="claude-opus-4-8, gpt-5.5-high, gemini-3.1-pro-high, gpt-5.6-sol">

Artifact: Draft Requirement Units (per the `requirements-authoring` skill's requirement-unit asset). Done when: every in-scope requirement has schema-complete draft and explicit user decision.

1. Draft in small batches using `<req>` schema 2. Use EARS for FRs and measurable metrics for NFRs 3. Keep unresolved or deferred units as `Draft` 4. Modify files directly, do not show to user 5. Update `<req>` schema if older/missing fields 6. Required skills: `requirements-authoring` 7. If reverse engineering - it must be possible to rewrite using requirements only completely from scratch without old code present.

</draft>

<validate phase="6" priority="must" subagent="reviewer" role="Quality reviewer checking correctness, conflicts, and gaps" subagent_required_model="gpt-5.4-medium, gemini-3.1-pro-preview, claude-sonnet-5, grok-4.5, gpt-5.6-terra" must-be-subagent>

Artifact: Validation Report (rubric results, conflict checks, gap checks, risks). Done when: checklist passes and unresolved issues are either fixed or explicitly deferred.

1. Run validation using the `requirements-authoring` skill's validation rubric 2. Run conflict checks and gap checks 3. Verify traceability source -> goal -> req -> test 4. HIT