# Requirements Style Guide (EARS): [Project name]

> Style guide for writing requirement sentences with the Easy Approach to
> Requirements Syntax (EARS), introduced by Mavin, Wilkinson, Harwood and
> Novak at the 17th IEEE International Requirements Engineering
> Conference (RE 2009, pages 317 to 322, DOI 10.1109/RE.2009.9). EARS uses
> a few keywords in a fixed order so that every requirement states its
> condition, the system and the response in the same way. Replace every
> `[bracketed]` value and every row marked *Example*.

<!-- Guidance: Agree this guide at the start of requirements work and check it in every review (`requirements/requirements-review-checklist`, check IR-09). Pick one system name and one keyword ("shall") and use them everywhere. -->

## 1. Generic structure

Every EARS requirement follows this clause order:

`While <precondition(s)>, when <trigger>, the <system name> shall <system response(s)>`

- Zero or more preconditions, introduced by **While**.
- Zero or one trigger, introduced by **When**.
- Exactly one system name.
- One or more system responses after **shall**.

Keep the clauses in this order. It matches the order in which things
happen, which makes requirements easier to read and to test.

## 2. Patterns

| Pattern | Keyword | Template | Example (fictional LeakWatch system) |
|---|---|---|---|
| Ubiquitous | none | The `<system>` shall `<response>`. | The LeakWatch console shall display the time of the last data received from each district. *(Example)* |
| State-driven | While | While `<precondition>`, the `<system>` shall `<response>`. | While the analytics service is unavailable, the LeakWatch console shall show raw sensor alarms. *(Example)* |
| Event-driven | When | When `<trigger>`, the `<system>` shall `<response>`. | When an operator confirms a leak alert, LeakWatch shall send the estimated location to the field app. *(Example)* |
| Optional feature | Where | Where `<feature is included>`, the `<system>` shall `<response>`. | Where pressure loggers are installed, LeakWatch shall show pressure data next to each alert. *(Example)* |
| Unwanted behaviour | If, then | If `<unwanted condition>`, then the `<system>` shall `<response>`. | If a sensor sends no data for 6 hours, then LeakWatch shall raise a sensor fault alert. *(Example)* |
| Complex | combination | While `<precondition>`, when `<trigger>`, the `<system>` shall `<response>`. | While training mode is selected, when an operator confirms an alert, LeakWatch shall not create a work order. *(Example)* |

## 3. Project rules

<!-- Guidance: Add the rules your project needs on top of the patterns. Keep the list short. -->

1. Use the system name "[system name]" exactly; never "the system" or "it".
2. Use "shall" for requirements, "will" for statements of fact, and never
   "should" or "may" in a requirement.
3. Use **If, then** only for unwanted behaviour (faults, misuse, bad
   input). Use **When** for expected events.
4. State values with units and tolerances, for example "within 60
   seconds".
5. Write one response per requirement unless the responses are always
   verified together.

## 4. Rewriting examples

| Before | Problem | After (EARS) |
|---|---|---|
| The system should alert quickly on leaks. *(Example)* | Vague subject, "should", no trigger or measure | When LeakWatch detects a leak pattern, LeakWatch shall raise an alert on the console within 60 seconds. |
| In case of lost connection the app saves data. *(Example)* | Unwanted condition not marked, no subject | If the field app loses network connection, then the field app shall store task updates and send them when the connection returns. |

## Standard and licence note

Based on A. Mavin, P. Wilkinson, A. Harwood and M. Novak, "Easy Approach
to Requirements Syntax (EARS)", 2009 17th IEEE International
Requirements Engineering Conference, pages 317 to 322,
https://doi.org/10.1109/RE.2009.9, and the pattern summary published by
the first author at https://alistairmavin.com/ears/. The pattern names
and the clause order come from those sources; the explanations and
examples are original text written for this collection. Related
templates: `requirements/system-requirements`,
`requirements/srs-iso-29148`, `requirements/operational-concept-opscon`.
Template licence: MIT.