ears-spec

name	ears-spec
description	Generates structured requirements using EARS (Easy Approach to Requirements Syntax) notation. Use when the user is planning a feature, entering spec mode, or asking for requirements. Produces user stories with testable acceptance criteria.

EARS Specification Generator

When the user asks you to plan, spec, or design a feature, produce structured requirements using this format. Do NOT produce free-form prose plans. Produce formal, testable specifications.

Output Structure

Generate THREE sections in this exact order:

Section 1: Requirements (requirements.md format)

For each requirement:

## Requirement N: [Short Name]
**Category:** [Functional | Security | Performance | UX | Accessibility | Error Handling]
**Priority:** [Must | Should | Could]

**User Story:** As a [role], I want [capability], so that [benefit].

**Acceptance Criteria:**
1. WHEN [condition/event] THE SYSTEM SHALL [expected behavior]
2. WHEN [condition/event] THE SYSTEM SHALL [expected behavior]
3. WHEN [error condition] THE SYSTEM SHALL [error handling behavior]

Use these EARS patterns:

• Ubiquitous: THE SYSTEM SHALL [behavior] (always true)
• Event-driven: WHEN [event] THE SYSTEM SHALL [response]
• State-driven: WHILE [state] THE SYSTEM SHALL [behavior]
• Optional: WHERE [feature enabled] THE SYSTEM SHALL [behavior]
• Unwanted/negative: IF [unwanted condition] THEN THE SYSTEM SHALL [countermeasure]

Section 2: Design Notes

For each major component affected:

• What changes and why
• Key data structures or API shapes
• Integration points with existing code
• Sequence of operations for complex flows

Section 3: Task Breakdown

Each task must reference its parent requirement:

- [ ] Task 1: [description] (Req 1, 3)
  - Depends on: none
  - Files: src/components/Feature.tsx, src/hooks/useFeature.ts
- [ ] Task 2: [description] (Req 2)
  - Depends on: Task 1
  - Files: src/api/feature.ts

Process

1. Read the user's request carefully
2. Ask 2-3 clarifying questions if critical details are missing
3. Generate initial requirements (aim for 10-20)
4. Challenge your own requirements:
   • Are there contradictions between any requirements?
   • What edge cases are missing?
   • What security considerations are unaddressed?
   • What error scenarios need handling?
   • What performance requirements are implicit?
5. Add the missing requirements you identified
6. Present the full spec for user review
7. Iterate based on feedback

Contradiction Detection

Before presenting the spec, scan for:

• Requirements that imply different behaviors for the same trigger
• Performance requirements that conflict with feature requirements
• Security requirements that conflict with UX requirements
• State any contradictions found and ask the user to resolve them

Example Output

Requirement 1: User Authentication

Category: Security Priority: Must

User Story: As a user, I want to log in with email and password, so that I can access my account securely.

Acceptance Criteria:

1. WHEN a user submits valid credentials THE SYSTEM SHALL issue a JWT token and redirect to the dashboard
2. WHEN a user submits invalid credentials THE SYSTEM SHALL display "Invalid email or password" without revealing which field is wrong
3. IF a user fails authentication 5 times within 15 minutes THEN THE SYSTEM SHALL lock the account for 30 minutes
4. WHILE a user session is active THE SYSTEM SHALL refresh the token 5 minutes before expiry
5. WHEN a user clicks logout THE SYSTEM SHALL invalidate the token server-side and clear client storage