mcpField
D
doc-ears

doc-ears

github.com/vladm3105Development1763 installsUpdated 1d ago
Repository

About doc-ears

A skill for authoring EARS requirements in layer 3 of an SDD flow, refining PRD content into atomic, testable, traceable statements. It defines five requirement patterns, measurable constraints, document structure, and a BDD-readiness gate.

Key features

  1. 01Write five EARS requirement patterns
  2. 02Keep statements atomic and testable
  3. 03Set measurable quality constraints
  4. 04Maintain IDs and PRD traceability
  5. 05Validate structure and readiness score

Use cases

  1. 01Turn PRD features into behavioral requirements
  2. 02Specify event, state, and error-handling rules
  3. 03Set measurable performance targets
  4. 04Prepare requirements for later BDD scenarios

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-ears

After installing, type/doc-earsin Claude Code to confirm it loaded.

Details

From the project README

doc-ears

Purpose

Create an EARS (Easy Approach to Requirements Syntax) document — Layer 3 of the SDD flow. EARS formalizes BRD/PRD requirements into precise, atomic, testable statements using WHEN-THE-SHALL-WITHIN syntax, ready for BDD translation.

Layer: 3 — a refinement step formalizing the Context (BRD) → Container (PRD) transition; it has no C4 level of its own. Upstream: PRD (Layer 2). (Upstream BRD lineage is reachable transitively via the @-tag chain per the necessary-upstream contract.) Downstream: BDD → ADR → SPEC → TDD → IPLAN → Code.

Each EARS statement must be testable (Given-When-Then derivable), measurable (quantifiable constraints), traceable (@prd), and atomic (one concept per statement).

When to Use

Use doc-ears when:

  • PRD (Layer 2) exists and you need formal requirements (the upstream BRD is reached transitively via the PRD's own @brd tags).
  • Translating product features into precise behavioral statements.
  • Establishing event-driven, state-driven, optional/feature-gated, error-handling, or system-wide rules.

For end-to-end generation from a PRD, a prompt, or an IPLAN, use ../doc-ears-autopilot/SKILL.md.

Prerequisites

Before writing, read:

  1. Template (source of truth): ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml
  2. Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md
  3. ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. Authoring style: ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
  5. Upstream PRD that drives this EARS (and, via the PRD's own @brd tags, the BRD it derives from).

Confirm no ID collision: ls docs/03_EARS/ 2>/dev/null. Reference only upstream documents that exist; never invent placeholders like PRD-XXX or TBD.

Layer Guidance

Required structure (5 numbered sections + glossary backmatter)

document_control is Section 1 (status, version, dates YYYY-MM-DD, priority, single @prd: source, BDD-Ready score, revision-history table). Then:

  1. Purpose & Context · 3. Requirements (the five patterns) · 4. Quality Attributes (tabular) · 5. Traceability.

Plus a Glossary backmatter section (glossary: template key — required, unnumbered). Section numbers and identifiers come from EARS-TEMPLATE.yaml's own # Section N: numbering — the template is the source of truth.

See EARS-TEMPLATE.yaml for per-section content and embedded authoring guidance.

The five EARS patterns (Section 3)
PatternSyntaxUse for
Event-DrivenWHEN [trigger], THE [component] SHALL [action] WITHIN [timing].user/API/timer events
State-DrivenWHILE [state], THE [component] SHALL [behavior] WITHIN [context].continuous / mode-dependent behavior
OptionalWHERE [feature enabled], THE [component] SHALL [behavior].feature-flagged / config-gated behavior
UnwantedIF [error], THE [component] SHALL [recovery] WITHIN [timing].failures, edge cases, fallbacks
UbiquitousTHE [component] SHALL [behavior] for [scope].global invariants, logging, audit

A genuinely multi-condition requirement composes these (e.g. WHILE [state], WHEN [event], THE … SHALL …) — composition, not a sixth pattern. EARS uses THE … SHALL … as the response clause, never a THEN connective.

Each requirement is atomic (one testable concept) and carries an element ID plus a per-requirement @prd: … traceability line. Use the Boundary Value Matrix, State Transition (with error states), and Fallback Path patterns from the template where they apply.

Quantifiable language (Sections 3 / 4)

Use SHALL / SHALL NOT / SHOULD / MAY correctly. Replace vague latency with percentiles: real-time → p50<100ms/p95<300ms/p99<1000ms; immediately → <500ms; fast/quickly → exact latency. Section 4 (Quality Attributes: Performance, Security, Reliability) is tabular with measurable targets: latency/response-time uses p50/p95/p99 notation, while a non-latency bound (cycle/iteration counts, event-windows, batch sizes, *.count) is quantified by a concrete value + unit (percentiles do not apply). Carry changeable values as @threshold: PRD.NN.category.key tags (no PRD section numbers in the tag).

Element IDs and tags
  • Hierarchical element IDs: EARS.{doc_id}.{section_id}.{hash} (e.g. EARS.01.03.c4d8; Requirements = section 03, Quality Attributes = section 04). Emit a stable 4-hex-char identifier per element, distinct within its section (HASH01); extend to 8 on collision. Do not compute SHA-256 in this prompt — the hash form is the canonicalization TARGET produced by a deterministic tool pass, and byte-exact field extraction is defined for BRD §7 only (Phase 2+ for EARS). Authority: framework/governance/ID_NAMING_STANDARDS.md.
  • EARS is Layer 3, so it carries the required @prd upstream tag (per the necessary-upstream contract). One @prd: only in Document Control (extras go in per-requirement tags); no ranges. Upstream BRD lineage is reachable transitively via the PRD's own @brd tags — do not emit @brd: on EARS elements.
  • Removed patterns (do not use): Event-XXX, State-XXX, UB-XXX, REQ-XXX; legacy 3-segment EARS.NN.xxxx; numeric type-code EARS.NN.25.SS; dash form EARS-NN-XXX.

Creation Process

  1. Read upstream — the PRD that drives these requirements (and, via its @brd tags, the BRD it derives from).
  2. Reserve ID — next free EARS-NN (two digits: EARS-01, EARS-99, EARS-102). Per-layer independence (CLEANUP-PR-F item 18): pick the next-free number in YOUR layer's index — the upstream's number is NOT your number (doc numbers are per-layer sequential and independent; see framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality).
  3. Create the nested folder — every EARS lives in docs/03_EARS/EARS-NN_{slug}/ regardless of size. Monolithic: EARS-NN_{slug}.md inside it; section-based (>25 KB): EARS-NN.S_{section}.md
    • index from ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md.
  4. Document Control (Section 1) first, then complete §2–§5 plus the glossary backmatter from the template.
  5. Categorize requirements into the five patterns; write atomic THE … SHALL … statements (WITHIN timing where applicable) with @threshold: constraints.
  6. Fill Quality Attributes (tabular; latency → percentiles, non-latency bounds → value + unit) and Traceability (@prd per the necessary-upstream contract).
  7. Update the EARS index docs/03_EARS/EARS-00_index.md in the same change.
  8. Validate (below) and commit the EARS and index together.

Validation

This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md and ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md.

  • Document Control is the first section.
  • All 5 sections present and non-empty.
  • Every statement uses WHEN-THE-SHALL-WITHIN syntax; SHALL/SHOULD/MAY correct.
  • Requirements categorized (Event, State, Optional, Unwanted, Ubiquitous) and atomic.
  • Element IDs match EARS.NN.SS.xxxx; no removed patterns.
  • Required upstream tag present: @prd (per the necessary-upstream contract); no ranges.
  • Single @prd: in Document Control; quantifiable constraints (no "fast").
  • No numeric downstream references to artifacts that do not yet exist.
  • Traceability matrix / index created or updated; no broken links.

Error codes (all severity error): XDOC-006 tag format invalid · XDOC-008 broken internal link · XDOC-009 missing traceability section.

Quality gate (blocking): BDD-Ready score ≥ 90/100 before moving on. If issues are found, fix and re-check; if unfixable, log for manual review.

Next Skill

../doc-bdd/SKILL.md — the BDD references this EARS (@ears: EARS.NN.SS.xxxx) and turns each statement into executable Given-When-Then scenarios. (BDD's required upstream is @ears only; further upstream lineage is reachable transitively via the @-tag chain.)

Adaptation

Read .aidoc/profile.yaml; honor only this skill's knobs (section_toggles, glossary). Ignore unknown keys; absent a profile, use framework defaults. Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.

Related Resources

  • Template / authoring rules: ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml
  • Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md
  • Index template: ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md
  • ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • Quality gate: ../doc-ears-audit/SKILL.md · Fixes: ../doc-ears-fixer/SKILL.md
  • Generation pipeline: ../doc-ears-autopilot/SKILL.md
  • Diagrams (state/sequence): ../charts-flow/SKILL.md

Quick Reference

PurposeFormalize requirements with WHEN-THE-SHALL-WITHIN syntax
Layer3 (refinement; no C4 level)
Upstream tags@prd (per necessary-upstream contract)
Key ruleOne atomic, testable, quantifiable statement each
Must includeDocument Control (first), five patterns, 5 sections
Quality gateBDD-Ready ≥ 90/100
Nextdoc-bdd

Comments

Markdown supported