# EARS Format Guidelines

## Overview
EARS (Easy Approach to Requirements Syntax) defines a structured grammar for writing acceptance criteria that are unambiguous, testable, and consistent.

EARS patterns describe behavior using a fixed logical structure — condition + subject + required response — and are language-neutral in their intent. All acceptance criteria must be written in the target language configured for the specification (`spec.json.language` / `{{LANG_CODE}}`).

**Language handling rule**: Keep EARS structural keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`) and translate only the variable content — `[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]` — into the target language. Do not translate the structural keywords themselves or embed target-language text inside the trigger phrases.

---

## Primary EARS Patterns

### 1. Event-Driven
- **Structure**: When [event], the [system] shall [response/action]
- **Apply when**: The behavior is triggered by a specific discrete event
- **Example**: When a user submits the registration form, the Auth Service shall create a new account record and send a verification email

### 2. State-Driven
- **Structure**: While [precondition], the [system] shall [response/action]
- **Apply when**: The behavior persists as long as the system is in a particular state
- **Example**: While a payment transaction is pending, the Order Service shall reject any cancellation request for the associated order

### 3. Error and Unwanted Behavior
- **Structure**: If [trigger], the [system] shall [response/action]
- **Apply when**: Specifying how the system responds to failures, invalid inputs, or undesired conditions
- **Example**: If the payment gateway returns a timeout error, the Checkout Service shall retry once and then present a failure message to the user

### 4. Optional Feature
- **Structure**: Where [feature is included], the [system] shall [response/action]
- **Apply when**: A capability exists only in certain product configurations or tiers
- **Example**: Where the enterprise license is active, the Admin Portal shall display the audit log export control

### 5. Unconditional (Ubiquitous)
- **Structure**: The [system] shall [response/action]
- **Apply when**: The behavior is always active, with no triggering condition
- **Example**: The API Gateway shall enforce a maximum request body size of 10 MB on all endpoints

---

## Combined Patterns

Use compound structures when behavior depends on both a persistent state and a discrete trigger:
- While [precondition], when [event], the [system] shall [response/action]
- When [event] and [additional condition], the [system] shall [response/action]

---

## Choosing the Right Subject

The EARS subject (`[system]`) should be a specific, named entity — not a generic placeholder:

- **Software features**: Use the concrete service or module name — e.g., "Notification Service", "Search Index Worker"
- **Process or workflow requirements**: Use the responsible role or team — e.g., "Review Process", "Operations Team"
- **Non-software domains**: Use the appropriate physical or organizational entity — e.g., "Deployment Pipeline", "Access Control Policy"

---

## Quality Criteria for Acceptance Criteria

A well-formed EARS statement satisfies all of the following:

- **Testable**: An automated or manual test can verify the requirement passes or fails
- **Singular**: Each statement describes exactly one behavior or response
- **Unambiguous**: No subjective terms — replace "quickly", "easily", or "reliably" with specific measurable values
- **Appropriately mandatory**: Use `shall` for mandatory behavior, `should` for strong recommendations
- **Syntactically valid**: Follows a recognized EARS pattern without mixing or omitting structural keywords
