SuperAPI AI Directory
Partner中文AI newsFavorites
Skillshaizei-ears-requirements

haizei-ears-requirements

Writing & research

View repository

Updated 10-16 08:41

About this skill

EARS requirements specification rewrite and review

This skill is used to rewrite vague, colloquial, or ambiguous requirements into clear, unambiguous, testable, reviewable specification statements based on EARS (Easy Approach to Requirements Syntax), and to provide sentence pattern choices, splitting suggestions, and validation opinions when needed.

The keywords in the following templates and shall retain their original English forms to ensure accurate EARS syntax expression.

File routing table

First determine which category the current task belongs to, then load the corresponding file according to the table below; do not default to reading all reference documents at once.

File When to check first Main content
SKILL.md Check first every time you enter the skill Trigger words, main process, mode routing entry, file division of labor
references/ears-usage-guide.md When you need to determine whether EARS is suitable, or understand use cases and common trigger methods Usage instructions, applicable scenarios, inapplicable scenarios, quick start
references/ears-chinese-output.md When you need to output Chinese requirements externally and do not want English keywords such as WHEN, WHILE, IF, THEN, WHERE, shall, etc. to appear Chinese output conventions, keyword replacement, Chinese templates
references/ears-patterns.md When you are unsure which EARS pattern to choose, or need to view details of each pattern and common errors Detailed explanation of the six patterns, examples, common errors
references/ears-output-template.md When you need a unified output structure, before-and-after rewrite comparison format, and template for issues to be confirmed Single-item rewrite, multi-item splitting, review template, output requirements
references/ears-writing-rules.md When you need to check writing quality, vague terms, testability, and completion criteria Writing rules, handling strategies, completion criteria
examples/ears-examples.md When you need to refer to specific rewrite cases Before rewrite / after rewrite examples

Default conventions for production output

  • When outputting requirements specifications externally, use Chinese sentence patterns by default and do not output WHEN、WHILE、IF、THEN、WHERE、shall and other English keywords.
  • English EARS keywords are only used in scenarios such as pattern explanation, classification description, internal discussion, or when the user explicitly requests retaining English templates.
  • Rewrite results use Chinese expressions such as "when...", "while...", "if..., then...", and "shall" by default.
  • If both a pattern explanation and the final specification need to be provided, first explain the pattern name, then output the Chinese specification body.

Rewrite process

Quick rewrite process

  1. Identify the original semantics: find the system name, action object, triggering event, state condition, exception condition, and constraint information.
  2. Mark problem points: circle vague terms, mixed multiple actions, unquantified constraints, missing subjects, and semantic drift risks.
  3. Determine whether to split: if one sentence contains multiple actions, multiple exception scenarios, or multiple timing stages, first split it into multiple requirements.
  4. Enter mode routing: according to whether there is an event, state, feature switch, or exception scenario, choose the corresponding EARS pattern.
  5. Execute rewrite：Output specifications according to the template, prioritizing the preservation of the original business intent, and do not add business rules on your own.
  6. Ensure testability：Fill in time limits, frequency limits, scope limits, failure handling, and prompt content as much as possible; when missing, list the questions to be confirmed.
  7. Output in a fixed structure：Provide the pattern judgment, before-and-after rewriting comparison, split explanation, and review comments.

Judgment and branching

  • If the original sentence expresses both “before the state change” and “after the state change” behaviors, it should be split into two items first, rather than directly retaining a complex pattern.
  • If a sentence contains both a normal flow and an exception flow, they should be rewritten separately, not written as one mixed requirement.
  • If it is impossible to clarify “who does what,” first add the subject, then rewrite.
  • If the trigger condition or response action cannot be clarified, stop forcing the rewrite and instead output the questions to be confirmed.

When used alone

  1. Receive vague specifications or requirements provided by the user.
  2. Classify each statement using the pattern selection guide.
  3. Rewrite the specification using the appropriate EARS template.
  4. Verify whether the rewritten specification meets the following requirements:
    • Each statement contains exactly one shall。
    • Use measurable, verifiable language.
    • Do not include ambiguous blacklist terms (see the USDM writing guide).
    • EARS keywords (WHEN, WHILE, IF, THEN, WHERE) must all be uppercase.
  5. Present show the user a before-and-after rewriting comparison.

When used together with USDM

EARS is applied at the specification level(SPEC-NNN) in the USDM hierarchy. In USDM Step 3 (hierarchy construction), each specification should be written using the appropriate EARS pattern:

  • Normal path behavior → Ubiquitous, Event-driven, or State-driven
  • Error / boundary scenarios → Unwanted behavior (IF-THEN)
  • Behavior dependent on a feature toggle → Optional feature (WHERE)
  • Multi-condition behavior → Complex

Pattern routing

6 EARS patterns

First determine from the table below which pattern should be used, then rewrite using the corresponding template.

Routing judgment Enter pattern Typical problem solved Template Example
There is no triggering event, no continuous state, and no feature toggle; the behavior always holds Ubiquitous Clearly state the generalized description that “the system should always do this” 系统 shall <响应>. 系统 shall 使用 AES-256 对静态数据进行加密。
There is a clear, discrete triggering event Event-Driven Clarify “when it happens” to avoid having an action without a trigger condition WHEN <触发事件>, 系统 shall <响应>. WHEN 用户点击“提交”按钮时，系统 shall 校验所有必填字段。
There is a continuously valid state or constraint State-Driven Clearly express “under what state it remains in effect” to avoid mistaking a state for an event WHILE <状态>, 系统 shall <响应>. WHILE 系统处于维护模式时，系统 shall 对所有请求返回 HTTP 503。
Handle errors, failures, boundary cases, or exceptional inputs Unwanted Behavior Write the handling actions for exceptional scenarios concretely, and avoid empty phrases like "handle properly" IF <条件>, THEN 系统 shall <响应>. IF 支付网关返回错误时，THEN 系统 shall 将待处理订单标记为支付失败。
The behavior only holds when a certain feature or configuration is enabled Optional Feature (Optional feature type) State the feature toggle precondition clearly, and avoid mistakenly writing an optional feature as default behavior WHERE <功能已启用>, 系统 shall <响应>. WHERE 已启用双因素认证时，系统 shall 在密码校验通过后要求输入 TOTP 验证码。
Two conditions exist at the same time, for example event + state, event + feature toggle Complex (Composite type) Combined conditions that a single mode is insufficient to express, but still limited to within two keywords Use WHEN, WHILE, IF, and WHERE in combination, and each specification uses at most 2 keywords WHILE 系统处于离线模式时，WHEN 用户新建记录时，系统 shall 将记录写入本地待同步队列。

Mode Selection Guide

Please select the correct mode according to the following decision process:

1. 是否存在触发事件？
   ├─ 是 → 是否还存在持续状态？
   │  ├─ 是 → 复合型（WHILE + WHEN）
   │  └─ 否 → 事件驱动型（WHEN）
   └─ 否
2. 是否存在持续条件？
   ├─ 是 → 状态驱动型（WHILE）
   └─ 否
3. 是否属于错误 / 故障 / 边界场景？
   ├─ 是 → 非期望行为型（IF-THEN）
   └─ 否
4. 是否依赖某个功能 / 配置？
   ├─ 是 → 可选功能型（WHERE）
   └─ 否 → 普适型

Reference materials (load as needed)

  • references/ears-usage-guide.md — usage instructions, trigger expressions, applicable and non-applicable scenarios
  • references/ears-chinese-output.md — Chinese production output conventions, keyword replacements, and Chinese templates
  • references/ears-patterns.md — detailed reference materials for the 6 modes, including multiple examples
  • references/ears-output-template.md — fixed output structure, comparison format, and templates for questions to be confirmed
  • references/ears-writing-rules.md — writing rules, typical handling strategies, and completion criteria
  • examples/ears-examples.md — before/after rewrite examples for typical scenarios