playbooks

home / skills / hexbee / hello-skills / ears-requirements

ears-requirements skill

/skills/ears-requirements

This skill converts natural language requirements into precise EARS statements, identifying patterns and ensuring measurable, testable outcomes.

npx playbooks add skill hexbee/hello-skills --skill ears-requirements

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.6 KB
---
name: ears-requirements
description: Write and rewrite textual system requirements using EARS (Easy Approach to Requirements Syntax). Use when converting ambiguous natural-language requirements into structured statements, classifying requirements into EARS patterns, or reviewing requirement quality for missing triggers, states, and measurable responses.
---

# Ears Requirements

## Overview

Transform requirement drafts into concise EARS-compliant statements, preserving intent while reducing ambiguity.

## Workflow

1. Extract requirement intent from user input.
2. Identify the correct EARS pattern:
   - Ubiquitous
   - State-driven
   - Event-driven
   - Optional-feature
   - Unwanted-behavior
   - Complex combinations
3. Rewrite each requirement using strict clause order and one clear system response.
4. Run a quality pass for measurability, testability, and missing conditions.
5. Return:
   - Rewritten requirement(s)
   - Pattern label for each
   - Brief rationale if pattern choice could be disputed

## Authoring Rules

- Keep one requirement per statement.
- Use exactly one explicit system subject (for example: "the ATM").
- Use `shall` for mandatory behavior.
- Prefer observable outcomes over implementation details.
- Keep conditions explicit; avoid implied triggers or hidden states.
- Avoid weak phrases such as "as appropriate", "if possible", "etc.".
- If numeric limits or timing are unknown, add a clear placeholder token (for example: `<MAX_LATENCY_MS>`).

## EARS Clause Order

Apply only the clauses needed by the chosen pattern, always in this order:

`While <state/precondition>, when <trigger>, the <system> shall <response>`

Use unwanted behavior pattern as:

`If <undesired trigger>, then the <system> shall <response>`

For pattern definitions and examples, read `references/ears-patterns.md`.

## Scripts

Use `scripts/validate_ears.py` to classify pattern and catch syntax/quality issues quickly.

Single requirement:

`python3 scripts/validate_ears.py --requirement "When mute is selected, the laptop shall suppress all audio output."`

Batch file (one requirement per line):

`python3 scripts/validate_ears.py --file requirements.txt`

Machine-readable output:

`python3 scripts/validate_ears.py --file requirements.txt --json`

## Quality Gate

Before finalizing, verify each requirement:

- Is testable with a pass/fail criterion.
- Has unambiguous actor, condition, and response.
- Uses consistent terminology with no synonym drift.
- Avoids combining multiple independent behaviors unless explicitly complex.
- Matches the selected EARS pattern.

If any check fails, provide a corrected version and explain the minimal change made.

Overview

This skill converts ambiguous or draft system requirements into EARS-compliant statements to improve clarity, testability, and traceability. It preserves original intent while enforcing EARS clause order, single-subject rules, and measurable responses. The result is a set of precise, testable requirements with pattern labels and short rationales when needed.

How this skill works

The skill extracts intent from user input, determines the correct EARS pattern (ubiquitous, state-driven, event-driven, optional-feature, unwanted-behavior, or complex), and rewrites each requirement using the mandated clause order and a single system subject. It runs a quality pass for measurability, testability, and missing conditions, returns rewritten statements, pattern labels, and brief rationales for disputed pattern choices.

When to use it

  • Converting informal or ambiguous requirements into structured EARS statements
  • Classifying existing requirements by EARS pattern for specification consistency
  • Reviewing requirements for missing triggers, states, or measurable responses
  • Preparing requirements for automated validation or test-case generation
  • Splitting combined behaviors into single-statement requirements

Best practices

  • Keep one requirement per statement with exactly one explicit system subject
  • Use shall for mandatory behavior and observable outcomes for responses
  • Follow the EARS clause order: While <state>, when <trigger>, the <system> shall <response>
  • Avoid vague qualifiers (e.g., as appropriate, if possible); insert numeric placeholders like <MAX_LATENCY_MS> when unknown
  • Run the quality gate: testability, clear actor/condition/response, consistent terminology

Example use cases

  • Take a product manager’s note and produce EARS-compliant requirements ready for review
  • Audit a requirement list and flag items missing triggers or measurable responses
  • Translate stakeholder conversations into single-statement, testable requirements
  • Classify a legacy requirements document into EARS patterns for modernization
  • Prepare requirements for use with scripts that validate syntax and produce machine-readable output

FAQ

What happens if intent is ambiguous?

I preserve the most likely intent and produce one or more alternative EARS statements with brief rationales; I mark ambiguous elements and suggest placeholder tokens for unknown numeric limits.

Can multiple behaviors be combined in one statement?

No. I split independent behaviors into separate EARS statements and note the minimal change required to maintain traceability.

Do you generate tests or only requirements?

I focus on clear, testable requirements; I will flag pass/fail criteria and measurable outputs, which can be directly used to create test cases.