# EARS spec template

Requirements an agent cannot misread. Five sentence patterns from Alistair Mavin's EARS notation, with worked examples. From tokenstoagents.ai/kit.

## Why patterns

"The form should handle errors gracefully" is a vibe. Every EARS statement has a trigger, a system, and a testable behavior, which means an agent can build against it and a test can verify it. The human job shifts from writing syntax to verifying logic. This template is the verifying-logic part.

## The five patterns

Ubiquitous (always true):
The system shall [behavior].
Example: The system shall render all text at AA contrast or better.

Event-driven (when):
When [trigger], the system shall [behavior].
Example: When the user submits the form with an invalid email, the system shall display the error message below the email field and move focus to it.

State-driven (while):
While [state], the system shall [behavior].
Example: While the form has unsaved changes, the system shall display the unsaved-changes indicator in the header.

Unwanted behavior (if-then):
If [unwanted condition], then the system shall [response].
Example: If the save request fails, then the system shall retain the user's input and display a retry action.

Optional feature (where):
Where [feature is present], the system shall [behavior].
Example: Where the workspace has autosave enabled, the system shall save drafts every 30 seconds without user action.

## The spec skeleton

    # Spec: [feature name]
    Status: draft | agreed | anchored
    Owner: [name]
    Level: spec-first | spec-anchored   (pick by cost of drift, not ambition)

    ## Intent (2 sentences, prose)
    What this feature is for and who it serves. This is the only vibes section.

    ## Requirements (EARS only)
    R1. When [trigger], the system shall [behavior].
    R2. While [state], the system shall [behavior].
    R3. If [failure], then the system shall [response].
    ...

    ## Design bindings
    Which components and tokens this feature uses:
    - Form fields: Input contract v1.0.0
    - Errors: color.feedback.danger via input.border-error
    - Layout: space.stack.default between fields

    ## Out of scope
    Name what this spec deliberately does not cover. Negative space prevents invention.

    ## Verification
    Each requirement maps to at least one test. R1 -> test name. No orphan requirements.

## Rules that keep it honest

One behavior per statement; "and" in a requirement is usually two requirements sharing a sentence. Every requirement gets an ID, because review conversations need handles. The design-bindings section is what ties the spec into the token and contract layers; a spec that names its tokens can be checked against them mechanically. And pick the level consciously: spec-first is fine for most work (write, build, discard), spec-anchored for surfaces where silent drift is expensive. The maturity levels are Birgitta Böckeler's; the honest note that nearly everyone runs spec-first is hers too.