EARS requirement pattern authoring. Use when writing requirements using EARS patterns (Ubiquitous, State-Driven, Event-Driven, Unwanted, Optional, Complex)...
EARS (Easy Approach to Requirements Syntax) pattern authoring for precise, unambiguous requirements.
Keywords: EARS patterns, ubiquitous requirements, state-driven requirements, event-driven requirements, unwanted behavior, optional features, complex requirements, SHALL keyword, requirement syntax
Use this skill when:
| Pattern | Keyword | Template |
|---|---|---|
| Ubiquitous | (none) | The <entity> SHALL <action> |
| State-Driven | WHILE | WHILE <condition>, the <entity> SHALL <action> |
| Event-Driven | WHEN | WHEN <trigger>, the <entity> SHALL <action> |
| Unwanted | IF...THEN | IF <condition>, THEN the <entity> SHALL <action> |
| Optional | WHERE | WHERE <feature>, the <entity> SHALL <action> |
| Complex | Multiple | Combination of patterns |
Start here: When does this requirement apply?
Always applies (no conditions) → Use Ubiquitous: "The system SHALL..."
While in a specific state → Use State-Driven: "WHILE in maintenance mode, the system SHALL..."
When something happens (event/trigger) → Use Event-Driven: "WHEN user clicks submit, the system SHALL..."
To handle unwanted behavior (error/exception) → Use Unwanted: "IF authentication fails, THEN the system SHALL..."
Only when feature is enabled (optional/configurable) → Use Optional: "WHERE dark mode is enabled, the system SHALL..."
Multiple conditions apply → Use Complex: "WHILE active, WHEN timeout occurs, the system SHALL..."
Use when: Requirement applies unconditionally, always active.
Template:
The <entity> SHALL <action>
Keywords: None required (no WHILE, WHEN, IF, WHERE)
Examples:
Common Mistakes:
Use when: Behavior applies while system is in a particular state.
Template:
WHILE <condition>, the <entity> SHALL <action>
Keywords: WHILE (at start)
Examples:
Common Mistakes:
Use when: Action triggered by a specific event or user action.
Template:
WHEN <trigger>, the <entity> SHALL <action>
Keywords: WHEN (at start)
Examples:
Common Mistakes:
Use when: Handling exceptions, errors, or unwanted conditions.
Template:
IF <condition>, THEN the <entity> SHALL <action>
Keywords: IF...THEN (both required)
Examples:
Common Mistakes:
Use when: Behavior depends on feature flag or configuration.
Template:
WHERE <feature/config>, the <entity> SHALL <action>
Keywords: WHERE (at start)
Examples:
Common Mistakes:
Use when: Requirement combines multiple conditions from different patterns.
Template:
<Pattern1>, <Pattern2>, the <entity> SHALL <action>
Examples:
Common Mistakes:
Always use SHALL for requirements:
Why: SHALL indicates mandatory behavior. Other words are ambiguous.
Always use active voice:
One action per requirement:
Requirements must be testable:
| Anti-Pattern | Problem | Fix |
|---|---|---|
| "should" instead of "SHALL" | Ambiguous obligation | Use "SHALL" |
| Passive voice | Unclear actor | Use active voice |
| Multiple requirements | Untestable compound | Split into separate |
| Implementation details | Specifies "how" | Focus on "what" |
| Vague terms | Not measurable | Add specific metrics |
| Wrong pattern keyword | Semantic confusion | Match pattern to behavior |
Before finalizing an EARS requirement:
EARS requirements map to canonical specification:
requirements:
- id: "REQ-001"
text: "WHEN a user submits the form, the system SHALL validate inputs"
priority: must
ears_type: event-driven # Matches pattern used
acceptance_criteria:
- id: "AC-001"
given: "a user on the form page"
when: "the user clicks submit"
then: "the system validates all inputs"
Detailed Documentation:
Related Skills:
canonical-spec-format - Canonical specification structurespec-management - Specification workflow navigationrequirements-quality - INVEST criteria and quality assessmentLast Updated: 2025-12-24