acceptance-criteria-ears

Writes testable acceptance criteria using the five EARS requirement patterns.

3|2|Updated Aug 24, 2026
One-click install
npx skills add https://github.com/hero-engine/hero --skill acceptance-criteria-ears-hero-engine
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: acceptance-criteria-ears
Source: https://github.com/hero-engine/hero/tree/main/domains/pm/skills/acceptance-criteria-ears
Command: npx skills add https://github.com/hero-engine/hero --skill acceptance-criteria-ears-hero-engine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Vague acceptance criteria force engineering to re-derive intent during handoff and let edge cases slip into production. This Skill provides the EARS (Easy Approach to Requirements Syntax) clause patterns so every criterion is unambiguously testable and survives the PM-to-engineering owner flip without rewriting. ## Core Features & Use Cases - Five EARS Patterns: Ubiquitous (THE SYSTEM SHALL), Event-driven (WHEN), State-driven (WHILE), Unwanted-behavior (IF/THEN), and Optional-feature (WHERE) templates with concrete examples for each. - Freeform Fallback Rules: Guidance on when numerical targets, referenced standards, data-shape constraints, and static content checks should skip EARS. - Pre-Handoff Checklist: A blocking review gate covering explicit triggers, observable behavior, error-path IF clauses, feature-flag WHERE clauses, and weasel-word elimination. - Use Case: A PM authoring a story spec writes three WHEN clauses for the happy path, adds IF/THEN clauses for payment-provider 5xx retries and 10MB upload rejection, and a WHERE clause for the enterprise-plan SSO gate, producing AC that engineering delivers against directly. ## Quick Start Ask the AI to write EARS acceptance criteria for a story about CSV export, including error paths and feature-flagged behavior.

Frequently Asked Questions about acceptance-criteria-ears

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write testable acceptance criteria for user stories?▼

Use the five EARS patterns: WHEN for event-triggered behavior, WHILE for state-dependent behavior, IF/THEN for error handling, WHERE for feature-gated behavior, and THE SYSTEM SHALL for invariants. Each clause must name an explicit trigger and an observable behavior a reviewer can verify.

What is the EARS requirements syntax?▼

EARS (Easy Approach to Requirements Syntax) is a constrained-natural-language pattern introduced by Alistair Mavin in 2009. It forces requirement authors to specify when behavior fires, what state triggers it, and what the system does in response, eliminating vague predicates.

When should I use freeform acceptance criteria instead of EARS?▼

Use freeform for non-functional requirements with numerical targets like p95 latency, referenced standards like WCAG 2.1 AA, data-shape constraints like export column lists, and static content checks. Mixing EARS clauses with freeform bullets in one story is normal and correct.

EARS vs Gherkin for acceptance criteria, which should I use?▼

Pick one shape per story rather than mixing them. EARS uses sentence templates (WHEN/IF/WHERE/SHALL) suited to dense spec documents, while Gherkin uses Given/When/Then scenarios. The companion acceptance-criteria-gherkin skill covers the Gherkin shape.

Why do acceptance criteria fail during PM to engineering handoff?▼

Handoff fails when AC contains weasel words like "as appropriate" or "when needed," lacks IF/THEN clauses for error paths, or prescribes UI implementation details. Tight EARS AC lets engineering deliver against the exact criteria PM authored without re-deriving intent.