doc-ears

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: BRD (Layer 1), PRD (Layer 2). Downstream: BDD → ADR → SPEC → TDD → IPLAN → Code.

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

When to Use

Use doc-ears when:

• BRD (Layer 1) and PRD (Layer 2) exist and you need formal requirements.
• Translating product features into precise behavioral statements.
• Establishing event-driven, state-driven, 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): framework/layers/03_EARS/EARS-TEMPLATE.yaml
2. Layer README: framework/layers/03_EARS/README.md
3. ID & tag standards: framework/governance/ID_NAMING_STANDARDS.md
4. Upstream BRD and PRD that drive this EARS.

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 sections)

## Document Control comes first (status, version, dates YYYY-MM-DD, priority, single @prd: source, @brd: reference, BDD-Ready score, revision-history table). Then:

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

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

The four 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
Unwanted	IF [error], THE [component] SHALL [recovery] WITHIN [timing].	failures, edge cases, fallbacks
Ubiquitous	THE [component] SHALL [behavior] for [scope].	global invariants, logging, audit

Each requirement is atomic (one testable concept) and carries an element ID plus a per-requirement @brd: … | @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 timing 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; all timing uses p50/p95/p99 notation. 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). hash = first 4 hex of SHA256("{doc_id}:{section_id}:{title}:{description}"), extend to 8 on collision.
• EARS is Layer 3, so it carries cumulative @brd and @prd tags. Format pipe-separated: @brd: BRD.01.07.a7f3 | @prd: PRD.01.09.1dbc. No ranges; one @prd: only in Document Control (extras go in per-requirement tags).
• 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 BRD and PRD that drive these requirements.
2. Reserve ID — next free EARS-NN (two digits: EARS-01, EARS-99, EARS-102).
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 framework/layers/03_EARS/EARS-00_index.TEMPLATE.md.
4. Document Control first, then complete all 5 sections from the template.
5. Categorize requirements into the four patterns; write atomic WHEN-THE-SHALL-WITHIN statements with @threshold: constraints.
6. Fill Quality Attributes (tabular, percentile timing) and Traceability (cumulative @brd/@prd).
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

The framework ships no runtime code — this skill is the validator. Apply the checklist against framework/layers/03_EARS/README.md and 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, Unwanted, Ubiquitous) and atomic.
• Element IDs match EARS.NN.SS.xxxx; no removed patterns.
• Cumulative tags present: @brd and @prd, pipe-separated, 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.

Code	Meaning	Severity
XDOC-006	Tag format invalid	error
XDOC-008	Broken internal link	error
XDOC-009	Missing traceability section	error

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), inherits cumulative @brd/@prd tags, and turns each statement into executable Given-When-Then scenarios.

Adaptation

Before applying defaults, read the project adaptation profile (.aidoc/profile.yaml). Honor only this skill's declared knobs: section_toggles (include or omit template-declared optional sections) and glossary (substitute preferred terms in generated prose). Ignore any unknown or out-of-surface key; absent a profile, use framework defaults. Authority: framework/governance/ADAPTATION.md.

Related Resources

• Template / authoring rules: framework/layers/03_EARS/EARS-TEMPLATE.yaml
• Layer README: framework/layers/03_EARS/README.md
• Index template: framework/layers/03_EARS/EARS-00_index.TEMPLATE.md
• ID & tag standards: 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	@brd, @prd (2, cumulative)
Key rule	One atomic, testable, quantifiable statement each
Must include	Document Control (first), four patterns, 5 sections
Quality gate	BDD-Ready ≥ 90/100
Next	doc-bdd