Writing requirements (EARS+)

MySpec writes requirements and their acceptance criteria in EARS+. Knowing the patterns makes generated requirements faster to review and easier to correct.

EARS stands for Easy Approach to Requirements Syntax. It was developed by Alistair Mavin and colleagues at Rolls-Royce. It uses a few keywords and a fixed clause order to turn loose sentences into precise, testable requirements. EARS+ adds patterns for acceptance criteria, so each criterion reads like a test case.

Why EARS+

• Less ambiguity. The keywords say exactly when a requirement applies.
• Consistency. Every requirement has the same shape, whoever wrote it.
• Easier testing. A criterion such as “WHEN … THEN … SHALL …” maps directly to a test.
• Gaps show early. If you can’t fill in the trigger or the response, some information is missing.

The requirement patterns

The clauses of an EARS requirement always appear in the same order:

WHILE <state>, WHEN <trigger>, the <system> SHALL <response>

Only the system and its response are required. Each pattern adds a keyword:

Examples:

• Ubiquitous: The system SHALL store all timestamps in UTC.
• State-driven: WHILE the device is offline, the app SHALL save new notes locally.
• Event-driven: WHEN a user selects “Export”, the system SHALL download the current table as a CSV file.
• Optional feature: WHERE two-step sign-in is enabled, the system SHALL ask for a one-time code after the password.
• Unwanted behavior: IF a payment is declined, THEN the system SHALL keep the order open and show the reason.
• Complex: WHILE an upload is in progress, WHEN the user closes the tab, the app SHALL ask for confirmation.

Unwanted-behavior requirements are the ones most often forgotten. They describe errors, failures and edge cases.

How acceptance criteria are written

In requirements.md, every functional requirement (FR-001, FR-002, …) has a description, the user roles it applies to, and acceptance criteria. Each criterion follows one of these EARS+ patterns:

You may also see WHERE for criteria that only apply when an optional feature is on. Criteria may be numbered AC1, AC2 and so on.

A functional requirement looks like this:

### FR-004: Password reset
**Description:** Users can reset a forgotten password by email.
**User Role:** Registered user
**Acceptance Criteria:**
- WHEN a user requests a reset for a registered email THEN the system SHALL send a reset link to that address
- WHEN a user opens a valid reset link AND enters a new password that meets the policy THEN the system SHALL save it and sign the user in
- IF the reset link has expired THEN the system SHALL show "This link has expired" and offer to send a new one
- IF the user is signed in WHEN they open a reset link THEN the system SHALL ask them to sign out first

Non-functional requirements (NFR-001, …) have a measurable target and a priority instead:

### NFR-001: Search performance
**Description:** Search results must appear quickly.
**Target:** 95% of searches return results in under 1 second
**Priority:** High

Requirements for an existing codebase

In the MySpec brownfield workflow, requirements.md lists only what changes. Added (AR-) and changed (CR-) requirements use the same EARS+ acceptance criteria. A changed requirement strikes through the old criterion and adds the new one below it:

### CR-001: Idle sign-out
**Description:** Idle sessions now end sooner to meet the new security policy.
**User Role:** All users
**Acceptance Criteria:**
- ~~AC1: WHEN a session has been idle for 60 minutes THEN the system SHALL sign the user out~~
- AC2: WHEN a session has been idle for 15 minutes THEN the system SHALL sign the user out

Removed requirements (BR-) have no acceptance criteria. They give the reason for the removal and point to where the original requirement is described in your code.

In the OpenSpec workflow, delta spec files use the same idea in OpenSpec’s own format: each requirement states what the system SHALL do, followed by scenarios written as WHEN … THEN … bullets. See Spec files.

Tips for reviewing generated requirements

Check these points when the Requirements file reaches you:

• One behavior per requirement. If a requirement does several unrelated things, ask for it to be split.
• Specific, not vague. Replace words such as “fast”, “easy”, “all” or “any” with values or named things: “within 2 seconds”, “admins and editors”.
• Errors are covered. For each important event, look for an IF … THEN criterion that says what happens when it goes wrong.
• Each criterion is testable. Read it as a test case. If you can’t say how you would check it, it needs more detail.
• What, not how. Requirements should not name frameworks, databases or architecture. Those belong in solution.md.
• Measurable targets. Every non-functional requirement needs a number you can measure.
• Consistent with the constitution. A requirement must not break a rule from constitution.md.
• Not too many conditions. A requirement with more than three conditions is usually clearer as two or more requirements.
• Hard to write means unclear. If a requirement is hard to express in EARS, information is usually missing. Settle it before moving on.

To fix what you find, select Request Changes on the file card, or use Request change and the feedback items on the AI review card. See Review each spec file. To ask what a requirement means without changing anything, use /btw, for example /btw what does FR-004 mean?. After the session, change requirements in an Edit session.

Learn more

• EARS, by Alistair Mavin: the official EARS resource.