EARS Requirements Translator

Translate user stories and informal requirements into precise, testable EARS format requirements.

Workflow

Step 1: Gather Requirements

Read all stories and requirements provided by user. Identify:

• •The system/component being specified
• •Functional behaviors described
• •Conditions, triggers, and states mentioned
• •Error scenarios and edge cases

Step 2: Ask Clarification Questions

Use AskUserQuestion to clarify ambiguities. Common questions:

• •What is the exact system/component name?
• •What are the specific thresholds or timing requirements?
• •Are there error conditions to handle?
• •Is this an optional feature or always present?

Continue until at least 90% confident about requirements.

Step 3: Select Output Format

Ask user preference:

• •Individual REQs: Each requirement listed separately with IDs (REQ-001, REQ-002...)
• •Grouped by feature: Requirements organized under feature headings

Step 4: Transform to EARS

Apply the appropriate EARS pattern for each requirement. See references/ears-patterns.md for pattern details.

Requirement Splitting: Always attempt to split compound requirements into individual atomic requirements:

• •If a requirement mentions multiple tools (e.g., "RSpec and Rubocop"), create separate requirements for each
• •If a requirement mentions multiple services or components, create separate requirements for each
• •If a requirement mentions multiple actions, create separate requirements for each
• •Use sub-numbering (1a, 1b, 1c) to indicate requirements derived from the same source

Pattern Selection:

• •Always active property → Ubiquitous (no keyword)
• •Continuous state dependency → State-Driven (While)
• •Discrete event trigger → Event-Driven (When)
• •Error/fault handling → Unwanted Behavior (If...Then)
• •Optional feature → Optional Feature (Where)
• •Multiple conditions → Complex (combine)

Testing & Linting Requirements: Requirements about testing (RSpec, Jest, pytest, etc.) and linting (Rubocop, ESLint, etc.) should use the Ubiquitous pattern because they describe always-active quality properties of the system:

• •"Tests shall pass" = always-active property
• •"Linter shall report no errors" = always-active property

Example transformations:

• •

  Input: "When claude runs rspec it passes"

• •

  Output: "The admin/ test suite shall pass all RSpec tests without errors."

• •

  Input: "When rubocop runs it has no errors"

• •

  Output: "The admin/ codebase shall pass Rubocop linting without errors."

Step 5: Validate with Checklist

For each requirement, verify:

Structure:

• • Correct EARS pattern
• • Explicit system name
• • One "shall" per requirement
• • Temporal ordering (precondition → trigger → system → response)

Content:

• • Verifiable/testable
• • Measurable criteria (no vague terms)
• • Units for numerical values
• • No escape clauses

Language:

• • Active voice
• • Consistent terminology

Step 6: Present Results

Show the EARS requirements to user with:

• •Requirement IDs
• •Pattern type used
• •Original source reference (which user story/requirement it came from)

Step7: Writing Results

Write the EARS requirements with concise format

Quick Pattern Reference

Example Transformations

Example 1: Splitting Compound Requirements

Input:

When CI sees changes in admin/ it runs rspec and rubocop

Output (Split + Pattern Selection):

REQ-001a [Event-Driven]
When CI detects changes in admin/, the CI pipeline shall execute RSpec for admin/.

REQ-001b [Event-Driven]
When CI detects changes in admin/, the CI pipeline shall execute Rubocop for admin/.

Output (Concise version):

When CI detects changes in admin/, the CI pipeline shall execute RSpec for admin/.
When CI detects changes in admin/, the CI pipeline shall execute Rubocop for admin/.

Example 2: Testing/Linting as Ubiquitous

Input:

When claude runs rspec in admin/ it passes without errors When claude runs rubocop in admin/ it passes without errors

Output (Ubiquitous Pattern):

REQ-001 [Ubiquitous]
The admin/ test suite shall pass all RSpec tests without errors.

REQ-002 [Ubiquitous]
The admin/ codebase shall pass Rubocop linting without errors.

Output (Concise version):

The admin/ test suite shall pass all RSpec tests without errors.
The admin/ codebase shall pass Rubocop linting without errors.

Example 3: User Story Transformation

Input (User Story):

As a user, I want to receive a notification when my file upload completes, so I know it's done.

Output (EARS):

REQ-001 [Event-Driven]
When a file upload completes successfully, the application shall display a success notification within 2 seconds.

REQ-002 [Unwanted Behavior]
If a file upload fails, then the application shall display an error message indicating the failure reason.

Output (Concise version):

When a file upload completes successfully, the application shall display a success notification within 2 seconds.
If a file upload fails, then the application shall display an error message indicating the failure reason.

Resources

• •references/ears-patterns.md - Complete EARS pattern reference with examples and quality checklist