EARS Acceptance Criteria

One criterion, one behavior, one test.

EARS (Easy Approach to Requirements Syntax) constrains free-text requirements to a few keyword-driven templates. The result is unambiguous, reviewable, and maps 1:1 to a test case.

The five patterns

Keywords combine. Compound: WHILE <state> WHEN <trigger> THE SYSTEM SHALL <response>. Keep SHALL (the obligation) in every line.

Template

<pattern keywords> THE SYSTEM SHALL <single observable response>
[within <measurable bound>].

• Trigger / condition / state — the precondition, in user-visible terms.
• SHALL <response> — exactly one behavior you can observe and assert.
• Bound (optional) — a number a test can check (time, count, size, %).

One atomic, verifiable behavior per criterion

• If a line contains "and" joining two behaviors, split it into two.
• If you can't picture the assertion, it's too vague — rewrite it.
• Responses must be observable (output, state change, status code), not

internal ("the system processes the data correctly").

• Prefer measurable bounds over adjectives ("fast", "large", "secure").

Good vs. bad

Pattern picker

Always true, no trigger? ............... Ubiquitous (THE SYSTEM SHALL …)
Reaction to a discrete event? .......... Event-driven (WHEN …)
Only while in a mode/state? ............ State-driven (WHILE …)
Error / fault / disallowed case? ....... Unwanted behavior (IF … THEN …)
Only when a feature/flag is present? ... Optional (WHERE …)

Attaching criteria to AIM tasks

Each EARS line becomes one --ac item (repeatable):

aim task create "Add login endpoint" \
  --ac "WHEN valid credentials are submitted THE SYSTEM SHALL return a session token." \
  --ac "IF credentials are invalid THEN THE SYSTEM SHALL respond 401 with no token." \
  --ac "WHILE 5+ failures occurred in 10 min THE SYSTEM SHALL rate-limit the account."

• Add one later: aim task edit <id> --add-ac "WHEN …".
• Tick a criterion off (1-based index) as it's met:

aim task edit <id> --check-ac 2.

• In a spec, these same lines live under each requirement in

requirements.md (see the spec-driven-development skill); the MCP create_task / create_tasks tools accept them via the ac field.

Checklist before you commit a criterion

• [ ] Uses an EARS keyword (WHEN / WHILE / IF…THEN / WHERE / bare SHALL).
• [ ] Exactly one behavior (no hidden "and").
• [ ] Response is observable and assertable.
• [ ] Trigger/state/condition is concrete, not vague.
• [ ] Measurable bound included where it matters.
• [ ] You could hand it to a tester and they'd write the same test.

If a criterion can't fail a test, it isn't acceptance criteria — it's a wish.