EARS requirements: syntax and examples

Published 21 October 2026

EARS — the Easy Approach to Requirements Syntax — is a set of five sentence patterns for writing a requirement in plain English: a keyword (While, When, Where, If) says when the requirement applies, and the rest of the sentence names the system and what it shall do. Below are the patterns, a template to copy, examples from one project, how to rewrite a requirement in EARS, shall vs must, EARS vs Gherkin and user stories, EARS in Kiro and Spec Kit, and when not to use it.

Requirements are not code at all, they are expectations about what the code does; it is the contract about what developers will be held accountable to.

— one commenter, from a safety-critical perspective, on Hacker News, 2026. Their example of an EARS requirement: “while an error is present, the software shall ignore keypresses”.

Alistair Mavin and colleagues at Rolls-Royce developed EARS while analysing airworthiness regulations for a jet engine control system, and published it in 2009 (Wikipedia). The paper starts from a familiar problem: “Stakeholder requirements are usually written in unconstrained natural language, which is inherently imprecise.” Its answer was “a small set of structural rules” that “allows all natural language requirements to be expressed in one of five simple templates” (Mavin et al., RE’09). The official guide is on Alistair Mavin’s site.

EARS syntax: the five patterns

Every EARS requirement has the same shape, with the clauses always in this order:

While [precondition], when [trigger],
the [system] shall [response].

Both the While and the When clause are optional. A requirement has any number of preconditions, at most one trigger, exactly one system and at least one response (Wikipedia). The keyword it starts with gives the pattern:

EARS template

Copy the pattern you need; one requirement per sentence. Square brackets are yours to fill in.

Ubiquitous
The [system] shall [response].

Event-driven
When [trigger], the [system] shall
[response].

State-driven
While [state], the [system] shall
[response].

Unwanted behaviour
If [unwanted trigger], then the [system]
shall [response].

Optional feature
Where [feature is included], the
[system] shall [response].

Complex
While [state], when [trigger], the
[system] shall [response].

EARS requirements examples

The customer portal from the other templates, where customers see and pay their company’s invoices. Each requirement below appears elsewhere on this site in another form — a functional requirement, a use case step, a non-functional requirement. Here it is in EARS.

FR-012  Ubiquitous (enforces RULE-07)
The portal shall show the Pay button
only to users with the Billing role.

FR-014  Event-driven
When the bank approves a card payment,
the portal shall mark the invoice
"Paid" with today's date.

FR-015  Event-driven
When an invoice is marked "Paid", the
portal shall email a receipt to the
billing contact.

FR-016  Complex
While an invoice is not paid in full,
when it is seven days past its due
date, the portal shall send one
payment reminder.

UC-03 5a  Unwanted behaviour
If the bank declines a card payment,
then the portal shall show "Your bank
declined the payment" and leave the
invoice "Open".

UC-03 5b  Unwanted behaviour
If the bank does not answer within 60
seconds, then the portal shall ask the
payment provider for the status before
any retry.

UC-03  State-driven
While an invoice is "Payment pending",
the portal shall not accept another
card payment for it.

NFR-007  State-driven
While 500 customers are using the
portal at once, the payment page shall
respond within 2 seconds for 95% of
requests.

CR-9  Optional feature
Where French invoices are included,
the portal shall show each invoice in
the language the customer chose.

The two If … then requirements come from the use case UC-03: they say what happens when the payment goes wrong, which “a customer can pay an open invoice by card” alone does not. The “Payment pending” requirement was a guarantee in the same use case — “the card is charged at most once” — written as something a tester can check.

How to write a requirement in EARS

1. Name the system, once. “The portal”, not “we”, “the user” or “it”. If a sentence needs two systems, it is two requirements.
2. Ask when it applies. Always: ubiquitous. When something happens: When. For as long as a state lasts: While. Only in some versions: Where.
3. Write one response with “shall”. Something a tester can see: a status, a message, an email, a number. “Promptly” and “gracefully” are not responses.
4. For every When, ask what happens if it goes wrong. Each answer is an If … then requirement. This is where missing requirements turn up: the bank declines, the bank does not answer.
5. Keep it to three preconditions or fewer. EARS “can and should be used for requirements with 0-3 preconditions”; beyond that, a list or a decision table is easier to read (QRA).
6. Read it to the person who will sign it off. EARS stays in plain English so that people without training in requirements can review it. If they cannot say whether it is right, rewrite it.

Rewriting a requirement in EARS: before and after

A requirement as it is often first written:

The system should handle failed
payments gracefully and send reminders
for overdue invoices.

In EARS, it becomes four requirements from the example above: UC-03 5a and 5b for the failed payment, the “Payment pending” state, and FR-016 for the reminder. Writing them raised the questions the first version hid: which message the customer sees, what happens to the invoice, how many days count as overdue, and how many reminders go out.

One question came later. When the client asked for part payments, the reminder had to cover invoices that were partly paid, so FR-016 changed from open invoices to every invoice not paid in full. The change impact analysis found the question, and the decision log records the answer.

EARS shall vs must vs should

EARS uses “shall”. Spec Kit’s template uses “MUST”. RFC 2119, which many technical specifications follow, treats the two as the same: MUST, or “the terms ‘REQUIRED’ or ‘SHALL’, mean that the definition is an absolute requirement of the specification”. SHOULD means “there may exist valid reasons in particular circumstances to ignore a particular item” (RFC 2119).

Pick one word for a requirement, say at the top of the document what it means, and do not use “should” for something that has to happen. Keep the word in the sentence apart from the priority: NFR-007 says “shall”, and its MoSCoW priority on the non-functional requirements page is Should. The sentence says what the system does; the priority says how much it matters for this release.

EARS vs Gherkin (Given/When/Then)

FR-014 both ways. In EARS: “When the bank approves a card payment, the portal shall mark the invoice ‘Paid’ with today’s date.” In Gherkin, from the functional specification example:

Given an open invoice for 1,250.00 EUR
When  the customer pays it by card, and
      the bank approves the payment
Then  the invoice shows "Paid" with
      today's date

They work together: the EARS sentence is the requirement, and the scenarios are examples that test it. More on scenarios in the Gherkin examples. On which format suits AI coding agents better, one commenter on Spec Kit’s EARS feature request: “I believe there are currently no evaluations that prove advantages of one format over another for use in coding agents” (GitHub, 2026).

EARS and user stories: acceptance criteria in EARS

A user story says who wants something and why; EARS can say what the system does, as its acceptance criteria:

As a customer, I want to pay an open
invoice by card, so that I don't have
to arrange a bank transfer.

Acceptance criteria
1. When the bank approves the payment,
   the portal shall mark the invoice
   "Paid" with today's date.
2. If the bank declines the payment,
   then the portal shall show the
   bank's reason and leave the invoice
   "Open".

This is how Kiro arranges its requirements file: user stories, each with acceptance criteria in EARS (Kiro).

EARS in Kiro, Spec Kit and OpenSpec

• Kiro writes requirements.md in EARS. Its documentation gives the pattern “WHEN [condition/event] THE SYSTEM SHALL [expected behavior]”, with the example “WHEN a user submits a form with invalid data THE SYSTEM SHALL display validation errors next to the relevant fields” (Kiro). The same page says that before design, Kiro can be asked to analyze the requirements for “logical inconsistencies, ambiguities, conflicting constraints, and gaps”. For bug fixes, it adds a line for what must not change — “WHEN [condition] THEN the system SHALL CONTINUE TO [existing behavior]” (Kiro) — a Kiro addition, not one of the five patterns.
• Spec Kit writes requirements as “System MUST [specific capability]” (Spec Kit). A feature request to add EARS gathered over 30 upvotes and was closed in July 2026, when a community EARS extension was added to Spec Kit’s extension catalog (GitHub).
• OpenSpec writes requirements with SHALL, and scenarios under them with WHEN and THEN (OpenSpec).

How the three lay out a whole spec is on the spec template page.

When not to use EARS

• More than three preconditions. The sentence gets too long to follow. List the conditions, or put them in a decision table and point the requirement at it (QRA).
• A formula. If the requirement is a calculation, write the calculation.
• Constraints that are not behaviour. “Card data never reaches our servers” is a constraint on the design, not a response to a trigger; Wikipedia notes that EARS is less suited to non-functional requirements of this kind.

QRA, who make a tool that checks requirements against EARS, put it this way: “it is more valuable to convey the meaning of the requirement than to force it into a template.”

EARS and AI coding agents

When Kiro adopted EARS, one commenter described the appeal: “Structured English that should be simpler for an LLM to parse and reason about” (Hacker News, 2025). An agent can also rewrite free-form requirements into EARS. What it cannot settle is whether the requirement is the right one. One person in r/systems_engineering, in a thread on how far to let AI touch requirements:

It’s good for ensuring EARS syntax and follows INCOSE guidelines. Not good at knowing if it’s the right requirement or has right value.

— r/systems_engineering, 2026

An agent can put FR-016 into perfect EARS with “three days” instead of seven, or for open invoices only. The pattern makes the sentence checkable; someone who knows what the client asked for still has to read it and agree.

Where Specroot fits

This is the problem Specroot works on: each requirement kept with the version that was agreed, so that when an EARS sentence changes — FR-016 from open invoices to every invoice not paid in full — the agent and the client read the same, current one. Specroot for teams using AI coding agents.