---
name: earslang
description: Writes, checks and converts requirements in earslang, a requirements language written in markdown, with one rule per list item, EARS sentence patterns (WHEN, WHILE, WHERE, IF, THEN) and BCP 14 keywords (MUST, SHOULD, MAY). Use when a project has .ears files, ears code blocks or an ears.mod file, when the user asks for requirements in earslang, or when fixing an earslang error such as E0015. Not for user stories, tickets or specs in other formats unless the user asks to convert them to earslang.
license: CC-BY-4.0
metadata:
  earslang-version: "0.1"
  home: https://earslang.com/
---

# Writing requirements in earslang

This skill teaches earslang 0.1. Everything it asks of you is in this
folder: this file and references/compiler.md.

## Where rules go

- In a file whose name ends in `.ears`, or in a fenced code block whose
  language is `ears` inside a markdown file.
- One rule per list item. A long rule can carry on onto an indented line.
- Inside an `.ears` file or an `ears` block, a list item or paragraph line
  that holds a keyword in capitals, or starts with an ID, is a rule; so is
  one that holds a lowercase "shall" and no structure word. The lines of a
  paragraph join, as a list item's continuation lines do, so a paragraph
  line with no keyword, before or after a rule's line in the same
  paragraph, is part of that rule. Everything else is prose: headings,
  tables, quotes and the other lines with no keyword.
- Save the files as UTF-8.
- Keep explanations, open questions and sources outside the rules. An open
  question with an ID, such as `Q1: Should we sync?`, fails (E0008), and a
  sentence of prose with a capital MUST in it is read as a rule. Put them in
  the markdown around the block, or write them without capitals.

## Check every change

Check the rules after every change:

- If you can run commands and the compiler, `ears`, is installed
  (`ears version` prints its version), follow
  [references/compiler.md](references/compiler.md), and finish only when
  the compiler reports no error and no warning.
- Otherwise, read each rule against this file, in particular "What the
  checks do not catch" and "Common mistakes" below, fix what they show,
  and tell the user that the rules were not checked by the compiler. If
  you can run commands, tell the user too that the compiler is not
  installed or did not start.

Do not paste the rules into a website or any other service to check them:
requirements can be confidential.

## Defaults

Unless the user or the project says otherwise:

- Write MUST, not SHALL. A project that uses SHALL sets `spelling shall` in
  its `ears.mod`.
- Write THEN after every condition, even before a system declared in
  `ears.mod`, where it may be left out.
- Give every rule an ID. Once one rule in a file has an ID, the checks warn
  about each rule that does not (W0008).
- Use the verb form, "The app MUST …", rather than "X is REQUIRED.", unless
  the rule is about a thing rather than an action.

## Patterns

Structure words (WHERE, WHILE, WHEN, IF and THEN) count only in capitals.
The same words in lowercase are ordinary text, except in a classic EARS
sentence: one with no structure word, such as "When the user saves, the app
shall write the file."

| Pattern | Write it as |
|---|---|
| Ubiquitous | `The <system> MUST <response>.` |
| State | `WHILE <state>, THEN the <system> MUST <response>.` |
| Event | `WHEN <trigger>, THEN the <system> MUST <response>.` |
| Optional feature | `WHERE <feature>, THEN the <system> MUST <response>.` |
| Unwanted | `IF <trigger>, THEN the <system> MUST <response>.` |
| Combined | `WHILE <state>, WHEN <trigger>, THEN the <system> MUST <response>.` |

```ears
- P1: The app MUST keep every change on the device until it is sent.
- P2: WHILE offline, THEN the app MUST show that changes are waiting.
- P3: WHEN the user closes a file, THEN the app MUST ask before discarding changes.
- P4: WHERE dark mode is on, THEN the app MUST use the dark colours.
- P5: IF the disk is full, THEN the app MUST warn the user.
```

Write every condition first and THEN once, after the last condition and
before the subject. A condition after THEN is an error (E0034). The commas
and the full stop are optional; write them, since that is the standard
form. A Combined rule needs a table of its cases (see "Two or more
conditions").

## Keywords

| Keyword | Means |
|---|---|
| MUST, MUST NOT | required, or forbidden |
| SHOULD, SHOULD NOT | recommended, or not recommended; going against it needs a reason |
| MAY | optional: the system is free to do it or not |
| SHALL, SHALL NOT | the same as MUST and MUST NOT |
| X is REQUIRED. X is RECOMMENDED. X is NOT RECOMMENDED. X is OPTIONAL. | MUST, SHOULD, SHOULD NOT and MAY, for a thing rather than an action |

- Exactly one keyword in each rule (E0012).
- A keyword counts only in capitals, with one exception: in a rule with no
  structure word, a lowercase "shall" is read as the keyword, so that
  classic EARS stays valid. A lowercase "must" is ordinary English.
- In a rule with no structure word, a lowercase "shall" counts even beside
  another keyword: "The app MUST say what it shall do." fails (E0012).
  Reword it.
- Write NOT in capitals, with one space after the keyword, and no emphasis.
  "MUST not delete", "MUST-NOT" and `MUST **NOT**` are errors (E0036), and
  so is any other spacing between the two words, or a dash with a space on
  each side ("MUST — not ever — store").
- Never write MAY NOT (E0021). Write MUST NOT for "not allowed", or MAY with
  what is allowed ("MAY skip the sync").
- Text in backticks or double quotes is ordinary text, so a rule can mention
  "MUST" without it counting.

## How to write a rule

1. **Name the system as the subject.** The subject is the thing that has the
   duty: "the app", "the server", "the export". Not the user. "The user can
   export a report" becomes "The app MUST let the user export a report."
2. **Give a keyword to a duty or a permission, and to nothing else.** A
   duty is something the system could fail to do; a permission (MAY) is
   something it is free to do or not. A definition, a reason, an example, a
   label, a reference to another document or a step for a person that the
   system has no part in is neither: keep it as prose, outside the rules
   and without "shall" (see "Where rules go"). "A draft is a change that
   has not been sent." defines a word. "The app MUST keep every draft on
   the device." is a duty. A duty written only in a note, a definition or
   other prose, such as "Note: drafts are never deleted.", is not a rule,
   and nothing checks it: write it as a rule, "The app MUST NOT delete a
   draft."
3. **Choose the strength.** MUST when not meeting the rule is a defect.
   SHOULD when exceptions are allowed, each with a reason. MAY only for
   what the system is free to do or not. When the rule comes from a source
   (the user's words, a document), the source's wording decides, not your
   own view of the rule: do not make a rule stronger or weaker than what
   was asked. The loose prose row under "Converting from other forms" says
   which wording asks for which keyword. If the row gives the wording no
   keyword ("we would like"), or keywords of two strengths ("should
   always"), ask the user.
4. **Put the conditions first, in capitals,** in the order WHERE, WHILE,
   then WHEN or IF, and write THEN once after the last one.
5. **Give it one duty.** Two things that can be met or tested apart are two
   rules. A list that is met all together is one duty.
6. **Make the response testable.** "within one second", not "quickly";
   "after three failed attempts", not "after a few".
7. **Give it an ID:** a letter, then letters, digits, hyphens, underscores or
   full stops, with at least one digit, then a colon and a space, such as
   `R7: `, `FR-001: ` or `APP-12.1: `. Do not give a used ID to another
   rule, even after its rule is dropped or deleted; the checks see only
   the IDs in the files.
8. **Put tags last,** after the full stop.

```ears
- D1: The export MUST include the date, the author and the title.
- D2: WHEN the user signs in three times with a wrong password, THEN the app MUST lock the account for ten minutes.
```

## Tags

| Tag | Means |
|---|---|
| none | in force |
| `[proposed]` | not yet agreed, so not in force |
| `[dropped]` | rejected; kept for the record, not in force |
| `[from R3]` or `[from R3, R4]` | derived from those rules, which must exist (E0027) |
| `[table T1]` | the cases of its conditions are in table T1 |

- A rule has at most one of `[proposed]` and `[dropped]` (E0023).
- Tags are lowercase. A tag in another case, or any other words in brackets
  at the end of a rule, is an error (E0024).
- A tag written before the full stop is not a tag: it is read as part of the
  response, and nothing reports it.
- `[from …]` names rules, not tickets. Put a ticket or a document in the
  front matter's `source:` line.

```ears
- G1: IF a change fails to send, THEN the app MUST NOT lose it.
- G2: The app SHOULD show the time of the next attempt. [from G1] [proposed]
```

## Writing a change

A plan or a ticket often states a change: what is new, what is kept and what
goes. Write the change into the sentence, not into a tag. A status tag says
whether a rule is agreed; new, kept and removed describe one change, and stop
being true once it lands.

- New: a plain rule.
- Removed: a prohibition of what the system does today.
- Kept: a duty to preserve what is true today.

An ID can name the change too, with the colon after it: here `RN` for new,
`RM` for removed and `RP` for kept.

```ears
- RN1: The export MUST include the date.
- RM1: The export MUST NOT write the old cache file.
- RP1: The export MUST preserve the CSV format.
```

## Two or more conditions

A rule with two or more conditions names a table in the same file (W0005
without one). The table sits under a heading whose first word is exactly the
table's name: `### T1 Saving while offline`. A colon after the name, as in
`### T1: Saving`, does not match (E0018). The table shows what happens in
every case of the conditions.

```ears
- C1: WHERE sync is on, WHILE offline, WHEN the user saves, THEN the app MUST queue the change. [table T1]

### T1 Saving while offline

| sync | network | the user saves | the app |
|---|---|---|---|
| on | offline | yes | queues the change |
| on | offline | no | does nothing |
| on | online | yes | sends the change |
| on | online | no | does nothing |
| off | offline | yes | keeps the change on the device only |
| off | offline | no | does nothing |
| off | online | yes | keeps the change on the device only |
| off | online | no | does nothing |
```

A table can also hold a long list that belongs to one rule, named the same
way.

## Front matter

Lines between two lines of `---` at the start of an `.ears` file or an
`ears` block are front matter. They apply to every rule in that file or
block.

- Each line is `key: value`. A key starts with a lowercase letter, followed
  by lowercase letters, digits, hyphens and underscores (E0011). The
  checks look at the key's form, not its value. An indented line continues
  the value above it.
- A value is plain text, not YAML: lists and quotes are kept as written.

```ears
---
source: Support requests about lost changes, ticket SUP-118
---

- F1: The app MUST save every change on the device within one second.
- F2: WHEN the network returns, THEN the app MUST send the waiting changes in the order they were made. [from F1]
- F3: IF the server refuses a change, THEN the app MUST keep the change and tell the user. [from F2]
- F4: The app SHOULD show how many changes are waiting. [proposed]
```

## Project file

A folder may hold an `ears.mod` file. It is optional.

```text
earslang 0.1
system the app
system the server
```

- The `earslang 0.1` line is required, once (E0003).
- Each `system` line names a subject. Once any is named, the subject of
  every rule with a verb (MUST, SHOULD, MAY and the rest) must be one of
  them (E0017), compared without regard to capital letters. This catches a
  misplaced comma or a misspelt subject.
- `spelling shall` says the project writes SHALL; the compiler's rewrites and
  its markdown, HTML and Gherkin exports then write SHALL instead of MUST.

## Converting from other forms

| From | Do this |
|---|---|
| Classic EARS ("When the user saves, the app shall write the file.") | Valid when a comma or "then" follows its conditions; without one, E0029, unless the subject is a system declared in `ears.mod`. Rewrite a valid one into the standard form (the compiler can do it: references/compiler.md), then check that each subject is the system. |
| Spec Kit (`**FR-001**: The system MUST …`) | Remove the bold. With the bold, the ID is read as part of the subject. |
| Gherkin Given | WHILE for a state, WHEN for an event. GIVEN is refused (E0019). |
| Gherkin When / Then | WHEN, then THEN with the system and a keyword such as MUST. Without the keyword the line is prose. |
| Gherkin And / But | A second condition with its own word, or a second rule. AND and BUT are not structure words (W0002). |
| Loose prose ("It would be good if the app showed the count, and it really needs to keep drafts on the device.") | One rule for each duty or permission, with the keyword its wording asks for and without the words that carried the strength: "The app SHOULD show the count." and "The app MUST keep drafts on the device." First, what the user can or may do becomes "The app MUST let the user …", and what a person must do becomes what the app requires or refuses; if the source does not show that the app has a part, ask the user. Then, said of the system: "must", "shall", "will", "has to", "needs to", "always", or a plain statement of what the system is to do, is MUST. "must not", "shall not", "will not", "never" or "is not allowed to" is MUST NOT. MUST and MUST NOT are one strength: "must never" is MUST NOT. "should", "ideally", "try to" or "it would be good" is SHOULD, and with "not" SHOULD NOT. "may" or "optionally" is MAY, and so is "does not have to" or "need not", with what the system may skip. "may not" can mean "not allowed" or "free not to": ask the user. Wording these give no keyword, or keywords of two strengths: ask the user. |
| A user story | A rule about what the system lets the user do. Keep "as a …" and "so that …" in the prose above it. |
| A response with "when" or "if" in it | Move the condition to the front, in capitals (W0009). |

```ears
- K1: WHILE the cart is empty, THEN the shop MUST refuse payment.
- K2: WHEN the user pays, THEN the shop MUST send a receipt.
```

## What the checks do not catch

These are read without an error or a warning, and mean something other than
what was written:

| Written | Read as | Write |
|---|---|---|
| `WHEN the user saves, THEN the app saves the file.` | prose, not a rule: there is no keyword | `WHEN the user saves, THEN the app MUST save the file.` |
| `The app MUST save WHEN the user quits.` | no condition; "WHEN the user quits" is part of the response, as is a capital IF or THEN after the keyword | `WHEN the user quits, THEN the app MUST save.` |
| `WHEN the user quits, THEN THEN the app MUST save.` | the subject is "THEN the app" | `WHEN the user quits, THEN the app MUST save.` |
| `R 7: The app MUST save.`, and the same with `R7:The`, `RX:`, `1R:` or `R#1:` | no ID; the text is part of the subject | `R7: The app MUST save.` |
| `- RN1 [new] The app MUST save.` or `- PROJ-106.1 The app MUST save.` | no ID; the ID and any tag are part of the subject | `- RN1: The app MUST save.` |
| `- [ ] The app MUST save.` | the box is part of the subject | `- The app MUST save.` |
| two `spelling` lines, or two `layout` lines, in `ears.mod` | the last one counts | one line of each |
| `The app MUST save [proposed].` | in force; "[proposed]" is part of the response | `The app MUST save. [proposed]` |

Read the rule back in the order the checks read it: conditions, THEN,
subject, keyword, response, tags.

## Common mistakes

| Code | Mistake |
|---|---|
| E0015 | a condition with no THEN before the subject |
| E0016 | THEN with no condition |
| E0034 | a condition after THEN |
| E0035 | words before the first condition, such as "Given the user is signed in," before WHEN |
| E0029 | no comma or THEN where the subject starts |
| E0012 | two keywords in one rule; split it |
| E0019 | GIVEN; use WHILE or WHEN |
| E0021 | MAY NOT or MAY not |
| E0036 | MUST, SHALL or SHOULD followed by "not" written another way, such as "MUST not" |
| E0008 | an ID with no keyword after it, such as on a question or a Gherkin step |
| E0010 | an ID used twice |
| E0011 | a front matter line that is not `key: value` |
| E0017 | a subject that is not a system in `ears.mod` |
| E0018 | `[table …]` names no heading with a table under it |
| E0024 | a tag that is not one of the four |
| E0027 | `[from …]` names a rule that does not exist |
| W0001 | a lowercase "must", or a "shall" beside a structure word, in a list item or in a paragraph with a structure word, read as prose |
| W0003 | a comma in the subject, often a condition in lowercase |
| W0004 | conditions out of the order WHERE, WHILE, WHEN or IF |
| W0005 | two or more conditions and no table |
| W0008 | a rule without an ID among rules that have one |
| W0009 | a lowercase "when", "while" or "if" in the response, which may hide a condition |

## Licence

CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Credit: earslang,
https://earslang.com/. The file follows the Agent Skills format
(https://agentskills.io/specification).
