#Requirements specs

A requirements spec defines what to build, in a format an agent can implement and a test can check. Four specs carry the requirements as a project moves from an idea to buildable work.

The PRD is where requirements are written precisely, and the rest of this page is how.

#EARS syntax

EARS (Easy Approach to Requirements Syntax) gives every requirement one of two shapes. Most are event-driven: a trigger, then the response the system owes.

When <trigger>, the system shall <response>.

For example:

When a user submits a form with invalid data, the system shall
show a validation error next to each affected field.

A requirement that always holds, with no trigger, uses the ubiquitous form:

The system shall return search results in under 300 ms at p95
with 500 concurrent users.

Both forms use "shall" for the behavior the system must exhibit. A conditional requirement written without a trigger, or one whose behavior cannot be observed, is a finding the verifier raises.

#Requirement kinds and IDs

Every requirement carries an ID and a kind, so it can be tracked from the PRD through design, stories, and code.

Each requirement also has a MoSCoW priority (must, should, could, won't) and a recorded source, so scope decisions trace back to where they came from.

#Acceptance criteria

A requirement is only as good as its acceptance criteria: the conditions that decide whether it was met. Each criterion is quantified, checkable, and independent, and it produces a pass or a fail.

For the search requirement above, an acceptance criterion reads:

A load test at 500 concurrent users shows p95 latency under 300 ms.

Vague words hide untestable requirements, so the verifier treats them as findings: fast, secure, scalable, user-friendly, intuitive, robust, seamless, and reliable each need a number, a threshold, or an observable outcome in their place.

#Epics and stories

A PRD states requirements; an epic groups them into a user-facing capability; a story is one buildable slice. Epics and stories carry their acceptance criteria in Gherkin, so they map straight to tests.

Given a signed-in user with an empty cart
When they add an in-stock item
Then the cart count increases by one
And the item appears in the cart summary

A story follows the As a [role], I want [feature], so that [benefit] form, carries a Definition of Ready and a Definition of Done, and satisfies INVEST: independent, negotiable, valuable, estimable, small, and testable.

#Traceability

Requirements are referenced by display ID across the whole chain, never copied. A PRD references its upstream brief by ID rather than restating it. An epic or feature lists the exact requirement IDs it covers, and every functional requirement is covered exactly once, so nothing is silently dropped and nothing is built twice. When a reviewer asks what implements FR-004, the answer is one traceable path from the PRD to the code.

On a PRD, open Requirements status at the end of the Requirements section to see each use case and non-functional requirement with its status (proposed, planned, in progress or built), the features that cover it and their pull requests.

#What the verifier looks for

Before you approve, the verifier agent checks requirements the way a test would. It reads across the whole set, not one line at a time, and raises a finding for:

• a requirement with no checkable acceptance criterion, or criteria that overlap ambiguously
• a subjective adjective with no threshold, unit, or timing behind it
• a non-functional requirement with no target a test could assert against
• missing error, empty, permission, lifecycle, or edge behavior for a stated flow
• two requirements that each make sense alone but cannot both hold

Resolve these in the review cockpit before the requirement moves downstream.

#Next steps

• Technical design specs: how the system gets built.
• Review findings: resolve findings before approval.
• Best practices: writing requirements that pass review.