name	ears-specifications
description	Use when writing formal specifications using the EARS (Easy Approach to Requirements Syntax) patterns — converting natural-language requirements, Gherkin scenarios, or user stories into testable, atomic specs with stable semantic IDs.

EARS Specifications

EARS (Easy Approach to Requirements Syntax) is a lightweight requirements format: every spec follows one of five patterns. Each spec should be small enough for a single red-green-refactor cycle.

The Five Patterns

Ubiquitous (always true): "The system shall [behavior]."
Event-driven (triggered by action): "When [trigger], the system shall [response]."
State-driven (while condition holds): "While [state], the system shall [behavior]."
Optional (feature-dependent): "Where [feature is enabled], the system shall [behavior]."
Unwanted (error handling): "If [unwanted condition], then the system shall [response]."

Semantic IDs

Use the format {FEATURE}-{TYPE}-{NNN}:

FEATURE: 2–4 letter prefix derived from the feature area (e.g., AUTH, CART, DASH)
TYPE: Component type — UI, API, DATA, NAV, BE, PROC
NNN: Sequential number, zero-padded (001, 002, ...)

Keep IDs stable. Don't renumber when inserting — use gaps or sub-numbers like AUTH-API-001a.

Converting from Gherkin

One Gherkin scenario often yields multiple EARS specs. Decompose each Given/When/Then into atomic, testable assertions.

Gherkin:

Scenario: Successful login
  Given a registered user
  When they submit valid credentials
  Then a session is created
  And they are redirected to the dashboard

EARS:

AUTH-API-001: When valid credentials are submitted, the system shall create a session.
AUTH-NAV-001: When a session is created, the system shall navigate to the dashboard.

Common Mistakes

Spec too big. If you can't write a single test that proves it, split it.
Two specs in one sentence. "When X, the system shall A and B." Split.
Renumbering on insertion. Once issued, an ID is permanent. Use gaps or 001a.
Compound TYPE. AUTH-UI-API-001 is two specs masquerading as one. Pick the dominant type, or split.

EARS Specifications

EARS (Easy Approach to Requirements Syntax) is a lightweight requirements format: every spec follows one of five patterns. Each spec should be small enough for a single red-green-refactor cycle.

The Five Patterns

Ubiquitous (always true): "The system shall [behavior]."

Event-driven (triggered by action): "When [trigger], the system shall [response]."

State-driven (while condition holds): "While [state], the system shall [behavior]."

Optional (feature-dependent): "Where [feature is enabled], the system shall [behavior]."

Unwanted (error handling): "If [unwanted condition], then the system shall [response]."

Semantic IDs

Use the format {FEATURE}-{TYPE}-{NNN}:

FEATURE: 2–4 letter prefix derived from the feature area (e.g., AUTH, CART, DASH)

TYPE: Component type — UI, API, DATA, NAV, BE, PROC

NNN: Sequential number, zero-padded (001, 002, ...)

Keep IDs stable. Don't renumber when inserting — use gaps or sub-numbers like AUTH-API-001a.

Converting from Gherkin

One Gherkin scenario often yields multiple EARS specs. Decompose each Given/When/Then into atomic, testable assertions.

Gherkin:

Scenario: Successful login Given a registered user When they submit valid credentials Then a session is created And they are redirected to the dashboard

EARS:

AUTH-API-001: When valid credentials are submitted, the system shall create a session.

AUTH-NAV-001: When a session is created, the system shall navigate to the dashboard.

Common Mistakes

Spec too big. If you can't write a single test that proves it, split it.

Two specs in one sentence. "When X, the system shall A and B." Split.

Renumbering on insertion. Once issued, an ID is permanent. Use gaps or 001a.

Compound TYPE. AUTH-UI-API-001 is two specs masquerading as one. Pick the dominant type, or split.

ears-specifications