Requirements with EARS Format

What Is EARS?

EARS stands for Easy Approach to Requirements Syntax. It is a structured format for writing software requirements that eliminates the ambiguity that plagues natural-language requirements.

Developed by Alistair Mavin, EARS provides five sentence templates — one for each type of requirement — that make requirements unambiguous, testable, and AI-implementable.

The 5 EARS Patterns

1. Ubiquitous: Always true. No trigger, no condition.

> The [system] shall [behavior].

2. Event-driven: Triggered by an event or action.

> When [trigger], the [system] shall [behavior].

3. State-driven: Active while a state is maintained.

> While [state], the [system] shall [behavior].

4. Unwanted behavior (if-then): Handles errors and exceptional conditions.

> If [condition], the [system] shall [behavior].

5. Optional feature: Only applies when a feature is enabled.

> Where [feature is enabled], the [system] shall [behavior].

EARS vs Vague Requirements

Compare:

• Vague: "The system should handle authentication."
• EARS: "When a user submits valid credentials, the system shall create a session token with a 24-hour expiry and redirect to /dashboard."

The EARS version tells a developer exactly what to build. The vague version tells them nothing useful.

12 EARS Requirements for User Authentication

REQ-001 (Ubiquitous): The system shall store all passwords using bcrypt hashing with a minimum cost factor of 12.

REQ-002 (Event-driven): When a user submits a valid email and correct password, the system shall create a session token with a 24-hour expiry and redirect to /dashboard.

REQ-003 (Unwanted behavior): If a user submits an email address not registered in the system, the system shall display "Invalid email or password" without indicating which field is incorrect.

REQ-004 (Unwanted behavior): If a user submits 5 consecutive incorrect passwords within 15 minutes, the system shall lock the account for 30 minutes and send a security notification email.

REQ-005 (State-driven): While a user's account is locked, the system shall reject all login attempts and display the time remaining until unlock.

REQ-006 (Event-driven): When a user clicks "Forgot Password", the system shall send a password reset email containing a one-time link valid for 60 minutes.

REQ-007 (Unwanted behavior): If a password reset link has expired, the system shall display "This reset link has expired" and offer to send a new one.

REQ-008 (Event-driven): When a user submits a new password via the reset form, the system shall validate the password meets minimum requirements (8+ characters, at least one number) before saving.

REQ-009 (Unwanted behavior): If a new password does not meet minimum requirements, the system shall display specific validation messages for each failed criterion without clearing the entered password.

REQ-010 (Event-driven): When a user successfully resets their password, the system shall invalidate all existing sessions for that user and redirect to the login page with "Password updated. Please log in."

REQ-011 (Optional): Where the user has enabled multi-factor authentication, the system shall require a valid TOTP code after successful password validation before creating a session.

REQ-012 (State-driven): While a session token is valid, the system shall automatically extend it by 24 hours on each authenticated API request.

How AI Uses EARS Requirements

Each REQ-xxx becomes a testable implementation target. When you run /kiro:spec-impl, the AI:

1. Reads requirements.md to understand all REQ-xxx items
2. Generates code that satisfies each requirement
3. Writes tests that verify each requirement independently
4. In the validation step, checks coverage against all requirements

The structured format means the AI can reason about requirements as discrete units rather than extracting intent from prose.

Requirement Traceability

Requirements trace through the entire pipeline:

• REQ-001 → referenced in design.md's "password service" section
• REQ-001 → assigned to task 1.2 "Implement password hashing service"
• REQ-001 → implemented in src/services/auth.service.ts, line 45
• REQ-001 → tested in src/services/auth.service.test.ts, line 23

This traceability means you can always answer: "Is REQ-001 implemented? Where? Is it tested?"

Key Takeaways

• The 5 EARS patterns: ubiquitous, event-driven, state-driven, unwanted behavior, optional feature
• EARS requirements eliminate ambiguity by using structured templates instead of prose
• Every requirement gets a unique ID (REQ-001) that traces through design, tasks, and code
• AI tools use EARS requirements as precise implementation targets with testable criteria
• Requirement traceability lets you verify that every requirement is implemented and tested