ears-authoring（耳朵创作）

EARS Authoring

EARS (Easy Approach to Requirements Syntax) pattern authoring for precise, unambiguous requirements.

When to Use This Skill

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:

• Writing new requirements using EARS syntax
• Converting informal requirements to EARS format
• Validating EARS pattern correctness
• Selecting the right EARS pattern for a requirement
• Understanding EARS anti-patterns

Quick Pattern Reference

Pattern Selection Decision Tree

Start here: When does this requirement apply?

1. Always applies (no conditions) → Use Ubiquitous: "The system SHALL..."
2. While in a specific state → Use State-Driven: "WHILE in maintenance mode, the system SHALL..."
3. When something happens (event/trigger) → Use Event-Driven: "WHEN user clicks submit, the system SHALL..."
4. To handle unwanted behavior (error/exception) → Use Unwanted: "IF authentication fails, THEN the system SHALL..."
5. Only when feature is enabled (optional/configurable) → Use Optional: "WHERE dark mode is enabled, the system SHALL..."
6. Multiple conditions apply → Use Complex: "WHILE active, WHEN timeout occurs, the system SHALL..."

Pattern Details

Ubiquitous Pattern

Use when: Requirement applies unconditionally, always active.

Template:

The <entity> SHALL <action>

Keywords: None required (no WHILE, WHEN, IF, WHERE)

Examples:

• "The system SHALL encrypt all data at rest"
• "The API SHALL respond in JSON format"
• "The application SHALL log all user actions"

Common Mistakes:

• Adding unnecessary conditions when behavior is universal
• Using "should" instead of "SHALL"

State-Driven Pattern

Use when: Behavior applies while system is in a particular state.

Template:

WHILE <condition>, the <entity> SHALL <action>

Keywords: WHILE (at start)

Examples:

• "WHILE in maintenance mode, the system SHALL display a banner"
• "WHILE the connection is active, the system SHALL send heartbeats"
• "WHILE the user is authenticated, the system SHALL show the dashboard"

Common Mistakes:

• Using WHEN instead of WHILE (WHEN = event, WHILE = state)
• Describing events, not states

Event-Driven Pattern

Use when: Action triggered by a specific event or user action.

Template:

WHEN <trigger>, the <entity> SHALL <action>

Keywords: WHEN (at start)

Examples:

• "WHEN a user submits the form, the system SHALL validate inputs"
• "WHEN an error occurs, the system SHALL log the details"
• "WHEN the session expires, the system SHALL redirect to login"

Common Mistakes:

• Using WHILE instead of WHEN (WHILE = state, WHEN = event)
• Describing states, not events

Unwanted Behavior Pattern

Use when: Handling exceptions, errors, or unwanted conditions.

Template:

IF <condition>, THEN the <entity> SHALL <action>

Keywords: IF...THEN (both required)

Examples:

• "IF authentication fails, THEN the system SHALL lock the account"
• "IF the database is unavailable, THEN the system SHALL queue requests"
• "IF input validation fails, THEN the system SHALL display error messages"

Common Mistakes:

• Using IF-THEN for normal behavior (use Event-Driven instead)
• Missing THEN keyword
• Using for positive conditions (reserve for negative/unwanted)

Optional Feature Pattern

Use when: Behavior depends on feature flag or configuration.

Template:

WHERE <feature/config>, the <entity> SHALL <action>

Keywords: WHERE (at start)

Examples:

• "WHERE dark mode is enabled, the system SHALL use dark theme"
• "WHERE audit logging is configured, the system SHALL log access"
• "WHERE two-factor authentication is enabled, the system SHALL require OTP"

Common Mistakes:

• Using IF instead of WHERE (IF = unwanted, WHERE = optional)
• Describing mandatory features as optional

Complex Pattern

Use when: Requirement combines multiple conditions from different patterns.

Template:

<Pattern1>, <Pattern2>, the <entity> SHALL <action>

Examples:

• "WHILE active, WHEN timeout occurs, the system SHALL reconnect"
• "WHILE in production mode, IF error occurs, THEN the system SHALL notify ops"
• "WHERE caching is enabled, WHEN data changes, the system SHALL invalidate cache"

Common Mistakes:

• Using Complex when a simpler pattern suffices
• Nesting conditions too deeply (max 2 recommended)

Writing Quality Requirements

The SHALL Keyword

Always use SHALL for requirements:

• ✅ "The system SHALL validate input"
• ❌ "The system should validate input"
• ❌ "The system must validate input"
• ❌ "The system will validate input"

Why: SHALL indicates mandatory behavior. Other words are ambiguous.

Active Voice

Always use active voice:

• ✅ "The system SHALL encrypt data"
• ❌ "Data shall be encrypted"
• ❌ "Encryption shall be performed"

Single Requirement Per Statement

One action per requirement:

• ✅ "The system SHALL validate input"
• ✅ "The system SHALL log validation errors"
• ❌ "The system SHALL validate input and log errors"

Testable Requirements

Requirements must be testable:

• ✅ "The system SHALL respond within 200ms"
• ❌ "The system SHALL respond quickly"
• ✅ "The system SHALL support 1000 concurrent users"
• ❌ "The system SHALL scale well"

Anti-Patterns to Avoid

Validation Checklist

Before finalizing an EARS requirement:

• Uses "SHALL" (not should/must/will)
• Uses active voice (entity does action)
• Single behavior per statement
• Testable with measurable criteria
• Pattern keyword matches behavior type
• No implementation details (what, not how)

Integration with Canonical Spec

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"

References

Detailed Documentation:

• Pattern Reference - Complete pattern syntax and rules
• Examples - Real-world examples per pattern

Related Skills:

• canonical-spec-format - Canonical specification structure
• spec-management - Specification workflow navigation
• requirements-quality - INVEST criteria and quality assessment

Last Updated: 2025-12-24

Version History

• v1.0.0 (2025-12-26): Initial release