Skip to content
OpenSmartRoute
Skillv1.0.0

doc-ears

Create EARS (Easy Approach to Requirements Syntax) formal requirements - Layer 3 of the SDD flow, translating PRD features into atomic, testable WHEN-THE-SHALL-WITHIN statements. Use after BRD and PRD

by vladm3105(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from vladm3105/aidoc-flow-framework (platforms/claude-code-plugin/skills/doc-ears/SKILL.md). Install upstream with npx skills add vladm3105/aidoc-flow-framework --skill doc-ears. Copyright stays with the author.

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)

Pattern Syntax Use for
Event-Driven WHEN [trigger], THE [component] SHALL [action] WITHIN [timing]. user/API/timer events
State-Driven WHILE [state], THE [component] SHALL [behavior] WITHIN [context]. continuous / mode-dependent behavior
Optional WHERE [feature enabled], THE [component] SHALL [behavior]. feature-flagged / config-gated behavior
Unwanted IF [error], THE [component] SHALL [recovery] WITHIN [timing]. failures, edge cases, fallbacks
Ubiquitous THE [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
Purpose Formalize requirements with WHEN-THE-SHALL-WITHIN syntax
Layer 3 (refinement; no C4 level)
Upstream tags @prd (per necessary-upstream contract)
Key rule One atomic, testable, quantifiable statement each
Must include Document Control (first), five patterns, 5 sections
Quality gate BDD-Ready ≥ 90/100
Next doc-bdd

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/vladm3105-aidoc-flow-framework-doc-ears/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

vladm3105-aidoc-flow-framework-doc-ears.ocm.jsonjson
{
  "ocm": "1",
  "id": "vladm3105-aidoc-flow-framework-doc-ears",
  "kind": "skill",
  "name": "doc-ears",
  "description": "Create EARS (Easy Approach to Requirements Syntax) formal requirements - Layer 3 of the SDD flow, translating PRD features into atomic, testable WHEN-THE-SHALL-WITHIN statements. Use after BRD and PRD exist. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-ears-autopilot`) drives this skill.",
  "publisher": "vladm3105",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "sdd-workflow",
      "layer-3-artifact",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Create EARS (Easy Approach to Requirements Syntax) formal requirements - Layer 3 of the SDD flow, translating PRD features into atomic, testable WHEN-THE-SHALL-WITHIN statements. Use after BRD and PRD exist. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-ears-autopilot`) drives this skill."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/vladm3105/aidoc-flow-framework",
      "path": "platforms/claude-code-plugin/skills/doc-ears/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/platforms/claude-code-plugin/skills/doc-ears/SKILL.md",
      "key": "vladm3105/aidoc-flow-framework/platforms/claude-code-plugin/skills/doc-ears/SKILL.md"
    }
  },
  "instructions": "# doc-ears\n\n## Purpose\n\nCreate an **EARS (Easy Approach to Requirements Syntax)** document — Layer 3 of\nthe SDD flow. EARS formalizes BRD/PRD requirements into precise, atomic, testable\nstatements using **WHEN-THE-SHALL-WITHIN** syntax, ready for BDD translation.\n\n**Layer**: 3 — a refinement step formalizing the Context (BRD) → Container (PRD)\ntransition; it has no C4 level of its own.\n**Upstream**: PRD (Layer 2). (Upstream BRD lineage is reachable transitively\nvia the @-tag chain per the necessary-upstream contract.)\n**Downstream**: BDD → ADR → SPEC → TDD → IPLAN → Code.\n\nEach EARS statement ",
  "cost": {
    "context_tokens": 2389
  }
}

Fetch it by URL: GET /api/v1/registry/vladm3105-aidoc-flow-framework-doc-ears/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.