Why Natural Language Stories Fail AI Agents
Standard Agile user stories ("As a user I want X so that Y") leave vital logic unspecified. LLMs like Cursor and Claude are forced to guess error states, retry limits, and authorization edge cases.
EARS (Easy Approach to Requirements Syntax) replaces ambiguity with 5 mathematical sentence patterns that ensure 100% testable criteria.
The 5 Core EARS Patterns
1. UBIQUITOUS (Always Active) PATTERN: The <system> shall <response>.
Used for continuous, non-negotiable system behaviors.
Example: The API shall encrypt all bearer tokens at rest using AES-256-GCM.
2. EVENT-DRIVEN (Triggered Action) PATTERN: WHEN <trigger>, the <system> shall <response>.
Used when an action occurs immediately after a specific event.
Example: WHEN the user clicks "Export ZIP", the client shall package the 4 markdown files and initiate a browser download within 500ms.
3. STATE-DRIVEN (Conditional Context) PATTERN: WHILE <in state>, the <system> shall <response>.
Used when behavior is constrained to a continuous operating state.
Example: WHILE the project is in Brownfield mode, the AI Architect shall generate a change proposal delta instead of scaffolding new files.
4. UNWANTED BEHAVIOR (Error Handling) PATTERN: IF <trigger/error>, THEN the <system> shall <response>.
Mandatory for error boundaries, rate limits, and fallback paths.
Example: IF the GitHub OAuth token is expired, THEN the authentication layer shall redirect to /login?error=token_expired and invalidate active sessions.
5. OPTIONAL FEATURE (Feature Toggles) PATTERN: WHERE <feature enabled>, the <system> shall <response>.
Used for gated features, premium tiers, or experimental flags.
Example: WHERE team collaboration is enabled, the editor shall stream live cursor positions of co-authors over WebSockets.
Automate EARS Syntax with MySpec
You don't need to memorize EARS syntax. MySpec's Socratic AI Architect automatically enforces EARS+ formatting during the interview phase, generating rigorous acceptance criteria for your requirements.md.
Generate EARS-Compliant Specs in 2 Minutes
Let MySpec format your messy user stories into strict EARS+ syntax.
