EARS Requirements

By the Syncfusion DevTutorials team · Last updated October 21, 2026

Write requirements in EARS, five fixed sentence patterns that an agent and a checker can both read. Cover the edge and error cases, and see why a spec is right for one stakeholder, not for every stakeholder.

"Handle It Gracefully"

Many specs have a line like this:

The export should handle errors gracefully.

It sounds like a good requirement.

But it does not tell the agent what to do.

What does "gracefully" mean? For example:

• Show an error message?
• Add a Retry button?
• Make a smaller file?
• Download nothing at all?

Different people may read it in different ways. The agent has the same problem, so it guesses.

It usually picks the simplest option. For example, it may write the error to the browser console, where users never see it.

Simple lesson: a vague requirement sounds useful, but the agent cannot act on it.

A Real-World Example

An airplane safety card does not say "Stay calm and handle emergencies well."

It says what to do in each situation:

• If the cabin loses pressure, oxygen masks drop.
• When the seatbelt sign is on, stay seated.
• While the plane is taxiing, keep bags stored.

Good requirements work the same way. They say what happens, and when.

Click the button and open the Agent tab.

• The vague line: the agent marks it NOT UNDERSTOOD.
• The four edge cases: the agent decides all of them on its own.

Now open Preview & Checks. Four checks fail.

The feature may look finished. But it does not do what the stakeholder expected, because the line never said what should happen.

Simple lesson: if a requirement is vague, it is still a guess.

TL;DR

1. EARS = Easy Approach to Requirements Syntax. It gives you five fixed patterns for writing requirements.

2. Every EARS line starts with one of five words:

   • The → always true
   • When → something happens
   • While → something stays true
   • If … then → something goes wrong
   • Where → a feature or role is on
3. Every EARS line uses shall exactly once.
4. One line = one behaviour.
5. Vague words like gracefully, fast and properly cannot be checked.

6. Most bugs hide in edge cases:

   • nothing to work with
   • too much to work with
   • something fails
7. A spec records what one stakeholder wants. Another stakeholder may want something else.

What You Will Learn

In this lesson, you will learn:

1. What EARS is and why a fixed pattern helps.
2. The five EARS patterns, and when to use each one.
3. The small rules every EARS line follows.
4. How to write requirements for edge cases and failures.
5. Why different stakeholders may want different behaviour.

The Five EARS Patterns

Why a Fixed Pattern Matters

People write requirements in many different ways.

One person writes:

The export should create a file.

Another writes:

Users must receive an Excel file.

A third writes:

Export functionality is expected.

All three may mean the same thing. But reviewers have to work out each one separately.

EARS fixes this with one shape. Every line has:

• a condition, if one is needed
• the word shall
• one clear behaviour

Because every line looks the same, people and tools can read requirements much faster.

EARS was first made by Alistair Mavin and his colleagues at Rolls-Royce.

Simple lesson: one fixed shape makes every requirement easy to read and easy to check.

Pattern 1: Always

Use this when something is always true.

Format:

The ... shall ...

Example:

The export shall write an .xlsx file.

There is no condition, because it is always true.

Pattern 2: Event

Use this when something happens at one moment.

Format:

When ..., the ... shall ...

Example:

When the user clicks Export, the grid shall download the visible rows.

This pattern fits clicks, requests and other actions.

Pattern 3: State

Use this when something stays true for a while.

Format:

While ..., the ... shall ...

Example:

While the grid has no rows, the Export button shall be disabled.

An empty grid is not an event. It is a state. It stays true until data appears.

Pattern 4: Something Goes Wrong

Use this when something fails.

Format:

If ..., then the ... shall ...

Example:

If the export fails, then the grid shall show an error message with a Retry button.

This pattern fits failures, bad input and other problems.

Pattern 5: Optional Feature

Use this when the behaviour applies only to some users, settings or features.

Format:

Where ..., the ... shall ...

Example:

Where the user has the Finance role, the export shall include the Margin column.

This pattern fits roles, permissions and feature flags.

The First Word Tells You the Pattern

Simple lesson: read the first word, and you know what kind of requirement it is.

The Small Rules

Use "Shall"

Every requirement uses the word shall.

Shall means the behaviour is required.

Words like should, must and will can mean different things to different people. One fixed word removes that doubt.

One Behaviour per Line

Each line describes only one behaviour.

This line has two:

When the user clicks Export, the grid shall download the file and shall show a toast.

• Download the file.
• Show a toast message.

Split it into two lines:

REQ-1: When the user clicks Export, the grid shall download the file.
REQ-2: When the user clicks Export, the grid shall show a toast.

Now each line can pass or fail on its own. You can see exactly which part broke.

Avoid Vague Words

These words cannot be measured or checked:

• gracefully
• fast
• properly
• user-friendly

Say exactly what should happen instead.

❌ Vague:

The export shall handle errors gracefully.

✅ Clear:

If the export fails, then the grid shall show an error message with a Retry button.

The clear line tells the agent what to build. It also gives testers something they can check.

Now watch a vague line become a valid EARS line. Each step fixes one rule.

The line passes only when every rule is green.

In simple words: if two developers can read a line and build different things, the line is not finished.

Edge and Error Cases

The Three Cases Most Teams Forget

Many specs only describe the happy path:

The user clicks Export.
The file downloads.
Everything works.

But most real problems happen somewhere else.

For almost every feature, ask three questions:

1. What happens when there is nothing?
2. What happens when there is too much?
3. What happens when something fails?

For example:

• an empty grid
• more rows than the limit
• a timeout or a server error

Each answer becomes its own EARS line. Usually:

• While fits an empty state.
• When fits a limit.
• If … then fits a failure.

Watch the vague line get replaced, one edge case at a time.

Each clear line turns one edge case green. Four lines, four passing checks.

Simple lesson: give every edge case its own line, or the agent will guess it.

Lab Exercise: Write the Edge Cases in EARS

The stakeholder has already said what should happen in each edge case.

Your task: replace the vague line with four clear EARS lines.

Watch the EARS Check panel while you type. Every line should get a green check.

When all lines pass, press Check my spec. Every edge-case test should pass.

One Spec, One Stakeholder

Different Stakeholders Want Different Things

Not every stakeholder wants the same behaviour.

One stakeholder may say:

When the grid is empty, export a file with only the headers.

Another may say:

When the grid is empty, disable the Export button.

Both answers are reasonable. Neither one is right for everyone.

The right answer depends on who asked. That is why you cannot copy requirements from one project to another.

Watch the same spec checked against two stakeholders.

The agent followed every line both times. The spec was simply written for someone else.

Simple lesson: a spec is not an answer sheet you can reuse. It records what one stakeholder asked for.

Practice: One More Feature

Now try another feature.

React app:

Bulk edit orders.

ASP.NET Core app:

Paged search results.

The ticket leaves several decisions open. Use stakeholder C's note to write the missing EARS lines.

Run it and compare the results.

A spec can pass for one stakeholder and fail for another. That does not mean the agent is broken. It means the spec was written for a different person.

What Changes per Tool

EARS is plain text, so it works with almost every spec tool.

The patterns stay the same in every tool. Only the place where you write them changes.

Common Mistakes

Exercises

These exercises help you practise writing clear EARS lines.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• EARS gives you five fixed patterns.
• The first word tells you the pattern.
• Every line uses "shall" once.
• One line, one behaviour.
• Vague words lead to guesses.
• A line that fails the EARS check does not help the agent.
• Every edge case needs its own line.
• A spec records what one stakeholder wants.

Further Reading

• EARS: the Easy Approach to Requirements Syntax, by Alistair Mavin: the original patterns, with examples.
• Kiro specs: how Kiro writes requirements in an EARS-style form.
• GitHub Spec Kit: where requirements live in a Spec Kit feature.

Next: Acceptance Criteria. You will learn how to write checks that catch bugs before users do, and make your first spec kit.