ears-translator

name

ears-translator

description

Translate user stories and informal requirements into EARS (Easy Approach to Requirements Syntax) format. Use when Claude needs to (1) convert user stories to formal requirements, (2) transform informal requirements into structured EARS format, (3) review and improve existing requirements using EARS patterns, (4) create testable, unambiguous system requirements. Triggers on requests like "convert to EARS", "write requirements", "formalize these user stories", "EARS format".

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

Pattern	Keyword	Template
Ubiquitous	(none)	The shall
State-Driven	While	While , the shall
Event-Driven	When	When , the shall
Unwanted Behavior	If...Then	If , then the shall
Optional Feature	Where	Where , the shall

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