How to write EARS acceptance criteria

This guide turns a loose requirement into an acceptance criterion in EARS notation — the Easy Approach to Requirements Syntax — so a human and an agent grade it identically. Use it whenever you are writing criteria for a PRD, feature spec, architecture doc, ADR decision driver, or Kiro requirements document. For the full description of the skill, see the ears-acceptance-criteria reference.

Step 1 — Identify the trigger type

Each EARS clause is chosen by when the behaviour applies. Classify your requirement into one of five patterns:

Ubiquitous — always true, no precondition.
Event-driven — triggered by an event (WHEN).
State-driven — holds during a state (WHILE).
Unwanted behaviour — guards against a condition (IF … THEN).
Optional feature — applies only where a feature is present (WHERE).

Step 2 — Write the clause in the matching template

Fill the template for your pattern. The system response always uses SHALL:

Ubiquitous:        The <system> SHALL <response>.
Event-driven:      WHEN <trigger>, the <system> SHALL <response>.
State-driven:      WHILE <state>, the <system> SHALL <response>.
Unwanted:          IF <condition>, THEN the <system> SHALL <response>.
Optional feature:  WHERE <feature>, the <system> SHALL <response>.

For example, “exports should be rejected while one is already running” becomes: WHILE an export is running, the system SHALL reject a new export request.

Step 3 — Make it gradeable

A criterion is only useful if both a person and a parser can decide pass or fail from it alone. Check each clause has exactly one observable response and no ambiguity (“fast”, “robust”, “as needed” fail this test). Split compound clauses into one EARS statement each.

Step 4 — Place the criteria in the host document

Drop the finished clauses into the acceptance-criteria section of the host genre. In a feature-spec or prd they sit under the requirement they refine; in kiro-requirements they follow each numbered user story. The compose-a-spec-set tutorial shows this in a full worked example.

Step 5 — Validate the host document

EARS criteria are plain text inside a MIF document, so validation is the host document’s own gate:

node scripts/mif-validate.mjs feature-spec.md --level 2

A VALID result confirms the document — criteria included — projects losslessly to JSON-LD.