Skip to content
mif-docs

Skill reference: ears-acceptance-criteria

Skill reference: ears-acceptance-criteria

Section titled “Skill reference: ears-acceptance-criteria”

The ears-acceptance-criteria skill is a substrate helper: it turns a requirement, decision driver, or finding into an acceptance criterion written in EARS notation — the Easy Approach to Requirements Syntax — so a human and an agent grade it identically. This reference describes the notation, how the skill produces it, when it earns its place, and its sources.

PropertyValue
AuthorsEARS-notation acceptance criteria
Purpose groupAuthoring helpers
MIF conceptTypesubstrate
Target MIF level2
Primary sourceEARS (Alistair Mavin)

What this document type is

Section titled “What this document type is”

EARS is a constrained natural-language pattern for requirements, introduced by Alistair Mavin and colleagues at Rolls-Royce and presented at RE2009. Its premise is that unconstrained prose requirements are ambiguous, while fully formal notations are unreadable; EARS sits between them, using a small set of keyword templates that keep a criterion in plain English yet make its trigger, condition, and required response unambiguous. A criterion written this way is testable by construction: the same sentence yields the same pass/fail verdict whether a person or a coding agent evaluates it.

EARS defines five patterns, distinguished by their leading clause.

PatternShapeUse
UbiquitousThe <system> shall <response>An always-true invariant
Event-drivenWHEN <trigger> the <system> shall <response>A discrete event
State-drivenWHILE <state> the <system> shall <response>A sustained condition
Unwanted behaviourIF <condition> THEN the <system> shall <response>Error/edge handling
Optional featureWHERE <feature> the <system> shall <response>A feature-gated case

A criterion that does not reduce to one of these shapes — that bundles several responses, or whose trigger is vague — is not a valid EARS statement, and the skill’s job is to refuse it and rewrite it.

How the skill produces one

Section titled “How the skill produces one”

ears-acceptance-criteria carries the five patterns as durable instructions plus eval cases and emits criteria other genres embed.

  • Pattern selection. The skill classifies each requirement by its trigger — invariant, event, state, unwanted condition, or feature gate — and casts it in the matching template, splitting compound requirements into one criterion each.
  • Eval cases. The skill ships evals/evals.json covering each pattern. As a substrate helper it carries no templates/ exemplars; the check-exemplars gate applies only to the genre skills.
  • MIF projection. The criteria are authored over a MIF floor via the shared mif-frontmatter substrate, and mif-validate proves the round-trip is lossless.

When it is beneficial

Section titled “When it is beneficial”

Reach for it whenever you are writing acceptance criteria — inside a PRD, a feature spec, an architecture document’s NFRs, an ADR’s decision drivers, or a Kiro requirements document. It is the shared grammar those genres depend on, so their criteria all grade the same way. The trade-off is discipline: EARS forbids the loose “the system should be fast” sentence, forcing a measurable response and an explicit trigger. That friction is the point — it is where ambiguity is caught.

It is not a document genre on its own; do not reach for it to write a whole spec. The host genre (prd, feature-spec, kiro-requirements, ai-architecture-doc) owns the document; this helper just shapes the criteria inside it.

Example

Section titled “Example”

A vague line — “login should handle bad passwords gracefully” — becomes the unwanted-behaviour criterion “IF the supplied password is invalid THEN the authentication service shall reject the attempt and return a 401 within 200 ms.” The trigger, system, and response are now explicit and a test can assert each.

Provenance & citations

Section titled “Provenance & citations”