requirements.md

Why requirements are a contract, not a wish list

Coding agents fail on unstated assumptions, not on syntax. "Handle payments reliably" leaves the retry policy, the idempotency window, and the failure path to the model's imagination. requirements.md removes the imagination: each behaviour is a numbered, testable statement with the actor, the trigger, and the response spelled out - including the unwanted behaviours (IF … THEN) that PRDs habitually omit.

• Numbered IDs (FR-001, NFR-001) give tasks, tests, and pull requests something to cite.
• Technology-neutral - the ORM, the framework, and the queue belong in solution.md; requirements must not prescribe them.
• Bounded by the constitution - a requirement that contradicts constitution.md is rejected at review.

Where it lives and when it is written

The greenfield collect substage is a clarification loop: the Business-Analyst prompt keeps asking focused multiple-choice questions (up to six rounds) until the list of requirements is complete, rather than guessing its way to a draft.

Structure of the greenfield file

# Requirements Specification: [Project Name]

## Overview
## User Roles
- Role 1: Description

## Functional Requirements
### FR-001: [Feature Name]
**Description:** What the system must do.
**User Role:** Which role(s) this applies to.
**Acceptance Criteria:**
- AC1: WHEN [event] THEN the system SHALL [response]

## Non-Functional Requirements
### NFR-001: [Category - e.g. Performance]
**Description:** What quality attribute must be met.
**Target:** Measurable target (e.g. "p95 response time < 200 ms")
**Priority:** High / Medium / Low

## Requirement Diagrams          (Mermaid requirementDiagram, FR and NFR groups)
## Data Requirements             (max 5 bullets)
## Integration Requirements      (max 5 bullets)

• Functional Requirements - each FR-NNN has a Description, the User Role it serves, and acceptance criteria in EARS+ form.
• Non-Functional Requirements - each NFR-NNN has a measurable Target and a Priority; a target you cannot measure is not a requirement.
• Requirement Diagrams - Mermaid requirementDiagram blocks, one for FRs and one for NFRs, generated from the entries above (see section 05).
• Data & Integration Requirements - at most five bullets each: entities and ownership, retention / privacy, fields needing encryption; external systems, exchange formats, authentication mechanism. Omitted entirely when they do not apply.

Writing acceptance criteria in EARS+

EARS (Easy Approach to Requirements Syntax, from Rolls-Royce) fixes the clause order and the modal verb so a sentence has one reading. EARS+ nests those patterns inside Agile acceptance criteria. Every AC in a MySpec bundle uses one of these shapes:

### FR-001: User Authentication
**Description:** Authenticated access to the application.
**User Role:** Registered user.
**Acceptance Criteria:**
- WHEN valid credentials are submitted THEN the system SHALL grant access and redirect to the dashboard
- IF invalid credentials are entered THEN the system SHALL display "Invalid username or password"
- WHEN 5 failed attempts occur within 15 minutes THEN the system SHALL lock the account for 30 minutes

### FR-002: Product Search
**Acceptance Criteria:**
- WHEN a search query is submitted THEN the system SHALL return matching products within 2 seconds
- WHEN no results are found THEN the system SHALL display "No products found" AND suggest related categories
- WHERE autocomplete is enabled THEN the system SHALL show suggestions after 3 characters are typed

### NFR-001: Performance
**Target:** Page loads within 3 seconds on standard broadband; 1000 concurrent users without degradation.
**Priority:** High
**Acceptance Criteria:**
- WHEN server load exceeds 80% THEN the system SHALL enable request queuing

Full grammar, the six base EARS patterns, and do's and don'ts: EARS Syntax Cheatsheet →

Requirement diagrams

The generator adds a ## Requirement Diagrams section after the NFRs: one Mermaid requirementDiagram for functional requirements (FR_001 nodes with verifymethod: test when they have acceptance criteria, linked by contains / derives / refines) and one for non-functional requirements (performanceRequirement or designConstraint nodes carrying the Target and Priority, linked to the FRs they constrain). Diagrams are capped at 20 nodes so they stay readable.

```mermaid
requirementDiagram
  functionalRequirement FR_001 {
    id: "FR-001"
    text: "Authenticated access to the application"
    risk: high
    verifymethod: test
  }
  performanceRequirement NFR_001 {
    id: "NFR-001"
    text: "p95 page load < 3 s at 1000 concurrent users"
    risk: high
    verifymethod: test
  }
  NFR_001 - refines -> FR_001
```

The Requirements Delta (AR / BR / CR)

For an existing codebase you do not re-specify the product; you specify the change. The MySpec brownfield workflow writes a # Requirements Delta grouped by impacted module, where every entry carries exactly one of three prefixes:

• AR-NNN - Add Requirement. A brand-new requirement, shaped exactly like a greenfield FR (Description, User Role, EARS+ ACs).
• BR-NNN - Remove Requirement. No acceptance criteria; a Description of why it goes and a Reference: file:line pointing at the code or comment that describes the original behaviour - a file the agent actually read.
• CR-NNN - Change Requirement. Each changed AC is reproduced ~~struck through~~ immediately above its replacement; unchanged ACs are not repeated.

# Requirements Delta: [Project Name]

## Overview
## Impacted User Roles
- Admin, End user

## Authentication            ← one section per impacted module

### AR-001: Token refresh endpoint
**Description:** Exchange a valid refresh token for a new access token.
**User Role:** End user.
**Acceptance Criteria:**
- AC1: WHEN a valid, unexpired refresh token is submitted THEN the system SHALL return a new 15-minute access token
- AC2: IF the refresh token is expired or revoked THEN the system SHALL return 401 and require re-login

### BR-001: Legacy session cookie
**Description:** The unsigned session cookie is superseded by bearer tokens.
**Reference:** src/auth/session.ts:42

### CR-001: Suspended Account Handling
**Description:** Suspended accounts must now be rejected at the auth middleware, not only at login.
**User Role:** Admin, End user.
**Acceptance Criteria:**
- ~~AC1: WHEN a suspended user logs in THEN the system SHALL reject the login~~
- AC2: WHEN any authenticated request arrives from a suspended account THEN the system SHALL reject it with 403

Numbering restarts per module (AR-001, BR-001, CR-001 can all live under the same heading), and the module names must be the ones the proposal's Technical Solution used - never invented here.

Authoring and review rules

How the rest of the bundle uses it

• solution.md must provide a design for every FR and map every measurable NFR to a Success Criteria row.
• tasks.md gives every requirement at least one task and lists the IDs on each task's _Requirements:_ line; its QA Verification milestone derives one verification task per FR from the acceptance criteria, negative IF … THEN paths included.
• Pull requests cite the IDs ("Satisfies FR-001, FR-002"), so reviewers check a diff against a sentence, not against a hunch.
• Through the MCP server, an agent reads the file with read_spec_file before implementing a task and can propose amendments with update_spec_file as a new, reviewable revision.