Requirements Documentation Authoring

Availability

OSS

TL;DR

Use this workflow for end-to-end requirements work: creating, updating, improving, reviewing, refactoring, or validating requirements. It is for cases where scope, expected behavior, or non-functional requirements need to be defined or clarified. The workflow moves through discovery, optional research, intent capture, outline, draft, validation, and finalization. It produces a Discovery Summary, optional Research Notes, Intent Capture, Requirement Outline, Draft Requirement Units, Validation Report, Final Requirements Set, Validation Pack, Traceability Matrix, Change Log, and requirements-authoring-flow-state.md. The main review gates are intent approval, outline approval, explicit approval for each requirement unit, review of validation findings, and final approval before delivery. If the request is implementation work, use the coding workflow instead.

When To Use This Workflow

When Not To Use This Workflow

Before You Start

How To Start

"Define requirements for the checkout flow covering discount codes, tax, and retries"
"Write requirements for the user onboarding experience with explicit actors, non-goals, and measurable performance thresholds"
"Review these payment requirements for contradictions, missing traceability, and weak NFR wording"
"Refactor our reporting requirements into atomic requirement units with stable IDs and approval gates"

How Rosetta Shapes This Workflow

Rosetta provides instructions. Coding agents act on them. Rosetta itself does not see user requests, code, or project data.

For this workflow, the always-active Rosetta behavior changes the experience in visible ways:

Workflow At A Glance

Phase What you provide What agents do What artifacts appear Review gate
Discovery Request, scope hints, existing requirements, glossary, assumptions, constraints Detect structure, read requirement context, identify FR/NFR/interface/data areas, record unknowns Discovery Summary, state update Questions if critical context is missing
Research Supporting docs, standards, prior decisions, measurable thresholds when local context is not enough Gather references, patterns, quality criteria, terminology constraints Research Notes, state update No approval gate; may be skipped with reason
Intent capture Goals, scope boundaries, non-goals, priorities, answers to targeted questions Restate intent, list assumptions, surface blockers Intent Capture, state update Explicit approval required
Outline Structure constraints, naming rules, ID expectations if you have them Propose MECE areas, file mapping, area abbreviations, ID strategy, traceability plan Requirement Outline, state update Explicit approval required
Draft Unit-by-unit decisions and corrections Draft atomic <req> units in small batches, use EARS for FRs, keep unresolved units as Draft Draft Requirement Units, state update Explicit decision for each requirement unit
Validate Review comments and any deferred items Run rubric, conflict checks, gap checks, source to goal to req to test traceability Validation Report, state update Review findings with user before finalization
Finalization Final approval decisions Deliver approved set, update index and links, update change log, complete state Final Requirements Set, Validation Pack, Traceability Matrix, Change Log, final state update Final review of delivered set

Workflow Overview

flowchart TD
    A["Start request"] --> B["Discovery"]
    B --> C{"Need extra sources?"}
    C -->|Yes| D["Research"]
    C -->|No| E["Intent capture"]
    D --> E
    E --> F{"Intent approved?"}
    F -->|No| E
    F -->|Yes| G["Outline"]
    G --> H{"Outline approved?"}
    H -->|No| G
    H -->|Yes| I["Draft small req batches"]
    I --> J{"Each req unit decided?"}
    J -->|No| I
    J -->|Yes| K["Validate"]
    K --> L{"Findings accepted or deferred?"}
    L -->|No| I
    L -->|Yes| M["Finalization"]

Interaction Flow

sequenceDiagram
    participant U as User
    participant A as Coding agent
    participant E as requirements-engineer
    participant R as requirements-reviewer
    participant X as Rosetta instructions

    U->>A: Ask to create, update, review, or validate requirements
    X-->>A: Enforce prep, questioning, approvals, and workflow order
    A->>E: Run discovery
    E-->>A: Discovery Summary
    opt Local context is insufficient
        A->>E: Run research
        E-->>A: Research Notes
    end
    A->>U: Present Intent Capture
    U-->>A: Approve or request corrections
    A->>E: Produce Requirement Outline
    E-->>A: Requirement Outline
    A->>U: Request outline approval
    U-->>A: Approve or request corrections
    loop Small draft batches
        A->>E: Draft req units
        E-->>A: Draft Requirement Units
        A->>U: Request explicit decision for each req unit
        U-->>A: Approve, reject, or defer units
    end
    A->>R: Run rubric, conflict checks, gap checks, traceability checks
    R-->>A: Validation Report
    A->>U: Review findings as narrative
    U-->>A: Accept fixes or defer issues
    A-->>U: Final Requirements Set, Validation Pack, Traceability Matrix, Change Log

Phases

1. Discovery

Goal: define the real scope before drafting starts.

2. Research

Goal: gather outside constraints only when local context is not enough.

3. Intent Capture

Goal: confirm what the workflow is trying to specify.

4. Outline

Goal: agree on structure before wording.

5. Draft

Goal: produce atomic requirement units that can be reviewed one by one.

The canonical <req> unit includes:

6. Validate

Goal: prove the set is consistent, complete enough for the approved scope, and ready for downstream work.

The validation rubric checks:

7. Finalization

Goal: package only the approved requirement set and its supporting review evidence.

How To Review Results

Check the artifacts in order.

Main failure modes to catch before approval:

Workflow-Specific Customization

Artifacts You Will Get

Common Mistakes

Source Files