# The EARS Notation Cheat Sheet

**How to write requirements that AI coding tools (and humans) can actually execute on**
*Part of the MxP Studio spec-driven development kit*

---

## What is EARS?

EARS stands for **Easy Approach to Requirements Syntax**. It's a small set of templates that force you to be specific about when something should happen and what the system should do.

It looks like this:

> **WHEN** [trigger], **THE SYSTEM SHALL** [behavior].

That's it. That's the whole idea.

Kiro generates requirements in EARS format by default. Lovable and Claude will follow EARS if you ask them to. Once you get used to writing acceptance criteria this way, you stop writing vague requirements *anywhere* — specs, tickets, bug reports, all of it.

---

## Why EARS matters for AI-native development

Traditional requirement: *"The system should handle login securely."*

What does "securely" mean? What does "handle" mean? The AI tool will guess. You'll get something. It won't match what you had in mind. You'll argue with it for three rounds.

EARS requirement:

> **WHEN** a user submits valid credentials, **THE SYSTEM SHALL** create a session and redirect to the dashboard within 2 seconds.
>
> **IF** the credentials are invalid, **THEN THE SYSTEM SHALL** display an error message and remain on the login screen without revealing which field was incorrect.
>
> **WHEN** a user fails to authenticate three times in five minutes, **THE SYSTEM SHALL** lock the account for 15 minutes and send a notification email.

Now the AI tool has something to build. And your tests write themselves.

---

## The five EARS patterns

### 1. Ubiquitous (always true)

**Template:** `THE SYSTEM SHALL [behavior].`

Use for: invariants that are always true, regardless of state or events.

**Examples:**
- THE SYSTEM SHALL encrypt all user data at rest.
- THE SYSTEM SHALL display the current date in the user's local timezone.
- THE SYSTEM SHALL log every write operation to the audit table.

---

### 2. Event-driven (triggered by something happening)

**Template:** `WHEN [trigger], THE SYSTEM SHALL [behavior].`

Use for: actions that fire in response to a specific user action or event.

**Examples:**
- WHEN a user clicks "Submit", THE SYSTEM SHALL validate the form and save the entry.
- WHEN a new comment is posted, THE SYSTEM SHALL notify the thread owner via email.
- WHEN the file upload completes, THE SYSTEM SHALL generate a thumbnail and display a success toast.

---

### 3. State-driven (true during a specific state)

**Template:** `WHILE [state], THE SYSTEM SHALL [behavior].`

Use for: behavior that's active only while the system is in a particular mode or state.

**Examples:**
- WHILE the user is editing a draft, THE SYSTEM SHALL auto-save every 30 seconds.
- WHILE a video is playing, THE SYSTEM SHALL prevent screen dimming.
- WHILE the user is offline, THE SYSTEM SHALL queue changes locally and display a sync indicator.

---

### 4. Unwanted behavior (what NOT to do, and how to recover)

**Template:** `IF [unwanted condition], THEN THE SYSTEM SHALL [behavior].`

Use for: error cases, edge cases, and graceful degradation.

**Examples:**
- IF the API returns a 500 error, THEN THE SYSTEM SHALL retry once with exponential backoff and show an error state if the retry fails.
- IF the user enters a password shorter than 12 characters, THEN THE SYSTEM SHALL prevent submission and show a specific inline error.
- IF the user session expires mid-action, THEN THE SYSTEM SHALL preserve their input and redirect to the login screen.

**This is the pattern most people skip.** It's also the one that separates real specs from fantasy specs. Every happy path has at least one unhappy variant. Name it.

---

### 5. Optional (feature-flagged or configurable)

**Template:** `WHERE [condition or feature], THE SYSTEM SHALL [behavior].`

Use for: behavior that only applies under certain configurations, feature flags, or user tiers.

**Examples:**
- WHERE the user is on the Pro tier, THE SYSTEM SHALL allow exports to CSV and PDF.
- WHERE the feature flag "new_onboarding" is enabled, THE SYSTEM SHALL show the three-step tutorial on first login.
- WHERE the workspace is on the Enterprise plan, THE SYSTEM SHALL enforce SSO for all members.

---

## Good spec vs. bad spec — side by side

### Bad (vague, un-buildable)

> The dashboard should load quickly and show the user's most important data. If something goes wrong, handle it gracefully. Make sure it works on mobile.

### Good (EARS-formatted, buildable)

> **WHEN** the user navigates to `/dashboard`, **THE SYSTEM SHALL** render the initial view with the user's last 7 days of activity within 1.5 seconds on a 4G connection.
>
> **IF** the activity data fails to load, **THEN THE SYSTEM SHALL** display a cached version with a "last updated" timestamp and a retry button.
>
> **IF** no cached version exists, **THEN THE SYSTEM SHALL** display an empty state with a specific message ("No activity yet — try [link to getting started]") rather than a generic error.
>
> **THE SYSTEM SHALL** render the dashboard responsively at viewport widths from 375px to 1920px.

Notice: no "quickly," no "gracefully," no "works on mobile." Every requirement is testable. An engineer (or an AI) can build this. A QA person (or an AI) can test it.

---

## How to prompt your AI tool to use EARS

When asking any AI coding tool to generate requirements, add this phrase:

> *"Write all acceptance criteria in EARS notation. Include at least one event-driven requirement (WHEN…), one unwanted-behavior requirement (IF…, THEN…), and any ubiquitous requirements (THE SYSTEM SHALL…) that matter. Do not use vague words like 'properly', 'appropriately', or 'as expected'."*

Paste that at the end of your prompt. You'll get dramatically better output on the first try.

---

## The red flags that mean your spec isn't really a spec

If you see any of these words in a requirement, rewrite it:

| Word | Why it's a problem |
|---|---|
| "properly" | Properly by whose definition? |
| "appropriately" | Same. |
| "as expected" | Expected by whom? You need to specify. |
| "user-friendly" | Not a requirement. An opinion. |
| "intuitive" | Untestable. |
| "fast" / "quickly" | Specify the number. 1.5s? 200ms? |
| "responsive" | Name the breakpoints. |
| "secure" | Name the specific security properties. |
| "robust" | Name the specific failure modes. |
| "scalable" | Name the specific load targets. |

**Translation table:**

| Bad | Good |
|---|---|
| "loads quickly" | "renders within 1.5 seconds on 4G" |
| "handles errors gracefully" | "IF the request fails, THEN THE SYSTEM SHALL show a retry button" |
| "user-friendly interface" | "all interactive elements are reachable within 2 tab stops from the page landing focus" |
| "secure authentication" | "IF a user fails auth 5 times in 10 minutes, THEN THE SYSTEM SHALL lock the account for 15 minutes" |

---

## A mini spec in EARS format — for reference

Here's what a complete mini-spec looks like for a simple feature: *"Users can save an article to read later."*

```
USER STORY
As a reader, I want to save articles I don't have time to
read right now, so I can come back to them later.

REQUIREMENTS

Ubiquitous:
- THE SYSTEM SHALL persist saved articles in the user's
  account across sessions.
- THE SYSTEM SHALL display the total count of saved articles
  in the user's navigation bar.

Event-driven:
- WHEN a user clicks the "Save" button on an article,
  THE SYSTEM SHALL add it to their saved list and show a
  toast confirmation within 500ms.
- WHEN a user visits their saved list, THE SYSTEM SHALL
  display articles in reverse-chronological order of save
  time.

State-driven:
- WHILE an article is already saved, THE SYSTEM SHALL
  display the Save button in its "Saved" state with an
  "Unsave" label on hover.

Unwanted behavior:
- IF the save request fails due to a network error,
  THEN THE SYSTEM SHALL queue the save locally and retry
  once connectivity is restored.
- IF a user attempts to save more than 500 articles,
  THEN THE SYSTEM SHALL prompt them to review and remove
  older saves before proceeding.

Optional:
- WHERE the user is on the Pro tier, THE SYSTEM SHALL allow
  saving with personal notes attached to each article.
```

Paste that into Kiro or Lovable and you'll get a buildable feature. That's the power of EARS.

---

## License

Use this cheat sheet freely. Print it. Tape it to your monitor. If it helps you ship something, tag [@ajbubb](https://linkedin.com/in/ajbubb) on LinkedIn.

*Built by AJ Bubb / MxP Studio.*