doc-ears Purpose
Create EARS (Easy Approach to Requirements Syntax) documents - Layer 3 artifact in the SDD workflow that formalizes requirements using the WHEN-THE-SHALL-WITHIN syntax.
Layer: 3
Upstream: BRD (Layer 1), PRD (Layer 2)
Downstream Artifacts: BDD (Layer 4), ADR (Layer 5), SYS (Layer 6)
Prerequisites Upstream Artifact Verification (CRITICAL)
Before creating this document, you MUST:
List existing upstream artifacts:
ls docs/BRD/ docs/PRD/ docs/EARS/ 2>/dev/null
Reference only existing documents in traceability tags
Use null only when upstream artifact type genuinely doesn't exist
NEVER use placeholders like BRD-XXX or TBD
Do NOT create missing upstream artifacts - skip functionality instead
Before creating EARS, read:
Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md Upstream BRD and PRD: Read the BRD and PRD that drive this EARS Template: ai_dev_flow/EARS/EARS-TEMPLATE.md (Template Version 3.0, primary authority) Schema: ai_dev_flow/EARS/EARS_SCHEMA.yaml (machine-readable validation rules) Creation Rules: ai_dev_flow/EARS/EARS_CREATION_RULES.md Validation Rules: ai_dev_flow/EARS/EARS_VALIDATION_RULES.md Template Binding (CRITICAL)
Always use these exact metadata values:
tags: - ears # NOT 'ears-requirements' or 'ears-formal-requirements' - layer-3-artifact - shared-architecture # OR 'ai-agent-primary' for agent docs
custom_fields: document_type: ears # NOT 'engineering-requirements' artifact_type: EARS layer: 3 architecture_approaches: [ai-agent-based, traditional-8layer] # ARRAY format required priority: shared development_status: active
When to Use This Skill
Use doc-ears when:
Have completed BRD (Layer 1) and PRD (Layer 2) Need to formalize requirements with precise behavioral statements Translating product features into formal requirements Establishing event-driven, state-driven, or conditional requirements You are at Layer 3 of the SDD workflow Document Structure (MANDATORY)
Per EARS-TEMPLATE.md, EARS documents require these sections:
Section Content Document Control Status, Version, Date, BDD-Ready Score, Source Document 1. Purpose and Context Document Purpose, Scope, Intended Audience 2. EARS in Development Workflow Layer positioning diagram 3. Requirements Event-Driven, State-Driven, Unwanted Behavior, Ubiquitous 4. Quality Attributes Performance, Security, Reliability (tabular format) 5. Traceability Upstream Sources, Downstream Artifacts, Tags, Thresholds 6. References Internal Documentation, External Standards Document Control Requirements
Required Fields (6 mandatory):
Status: Draft/In Review/Approved/Implemented Version: Semantic versioning (e.g., 1.0.0) Date Created/Last Updated: YYYY-MM-DD Priority: High/Medium/Low Source Document: Single @prd: PRD.NN.EE.SS value (NO ranges, NO multiple @prd values) BDD-Ready Score: Format XX% (Target: ≥90%)
Source Document Rule (E044):
VALID - Single @prd reference
| Source Document | @prd: PRD.01.07.01 |
INVALID - Range or multiple values
| Source Document | @prd: PRD.12.19.01 - @prd: PRD.12.19.57 |
EARS Syntax Patterns 1. Event-Driven Requirements
WHEN [triggering condition] THE [system] SHALL [response] WITHIN [constraint]
WHEN [trigger condition], THE [system component] SHALL [action 1], [action 2], and [action 3] WITHIN [timing constraint].
Example:
WHEN trade order received, THE order management system SHALL validate order parameters WITHIN 50 milliseconds (@threshold: PRD.035.timeout.order.validation).
- State-Driven Requirements
WHILE [system state] THE [system] SHALL [behavior] WITHIN [constraint]
WHILE [state condition], THE [system component] SHALL [continuous behavior] WITHIN [operational context].
- Unwanted Behavior Requirements
IF [error/problem] THE [system] SHALL [prevention/workaround] WITHIN [constraint]
IF [error condition], THE [system component] SHALL [prevention/recovery action] WITHIN [timing constraint].
- Ubiquitous Requirements
THE [system] SHALL [system-wide requirement] WITHIN [architectural boundary]
THE [system component] SHALL [universal behavior] for [scope/context].
Code Block Formatting (MANDATORY)
Always use triple backticks for EARS statements:
EARS.01.25.01: Requirement Name
WHEN [condition],
THE [component] SHALL [action]
WITHIN [constraint].
Traceability: @brd: BRD.01.01.01 | @prd: PRD.01.07.01
Unified Element ID Format (MANDATORY)
Pattern: EARS.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)
Element Type Code Example EARS Statement 25 EARS.02.25.01
Category ID Ranges:
Category ID Range Example Event-Driven 001-099 EARS.01.25.001 State-Driven 101-199 EARS.01.25.101 Unwanted Behavior 201-299 EARS.01.25.201 Ubiquitous 401-499 EARS.01.25.401
REMOVED PATTERNS - Do NOT use:
Category prefixes: E-XXX, S-XXX, Event-XXX, State-XXX 3-segment format: EARS.NN.EE Dash-based: EARS-NN-XXX BDD-Ready Scoring System
Purpose: Measures EARS maturity and readiness for BDD progression.
Format in Document Control:
| BDD-Ready Score | 95% (Target: ≥90%) |
Status and BDD-Ready Score Mapping BDD-Ready Score Required Status ≥90% Approved 70-89% In Review <70% Draft Scoring Criteria
Requirements Clarity (40%):
EARS statements follow WHEN-THE-SHALL-WITHIN syntax: 20% Each statement defines one testable concept (atomicity): 15% All timing/constraint clauses are quantifiable: 5%
Testability (35%):
BDD translation possible for each statement: 15% Observable verification methods defined: 10% Edge cases and error conditions specified: 10%
Quality Attribute Completeness (15%):
Performance targets with percentiles: 5% Security/compliance requirements complete: 5% Reliability/scalability targets measurable: 5%
Strategic Alignment (10%):
Links to business objectives traceable: 5% Implementation paths documented: 5%
Quality Gate: Score <90% blocks BDD artifact creation.
Quality Attributes Section
Use tabular format for quality attribute requirements:
Performance Requirements QA ID Requirement Statement Metric Target Priority Measurement Method EARS.NN.02.01 THE [component] SHALL complete [operation] Latency p95 < NNms High [method] EARS.NN.02.02 THE [component] SHALL process [workload] Throughput NN/s Medium [method] Quality Attribute Categories Category Keywords for Detection Performance latency, throughput, response time, p95, p99 Reliability availability, MTBF, MTTR, fault tolerance, recovery Scalability concurrent users, data volumes, horizontal scaling Security authentication, authorization, encryption, RBAC Observability logging, monitoring, tracing, alerting, metrics Maintainability code coverage, deployment, CI/CD, documentation Formal Language Rules
Mandatory Keywords:
SHALL: Mandatory requirement (do this) SHALL NOT: Prohibited requirement (never do this) SHOULD: Recommended requirement (preferred but not mandatory) MAY: Optional requirement (allowed but not required)
Avoid ambiguous terms: "fast", "efficient", "user-friendly" Use quantifiable metrics: "within 100ms", "with 99.9% uptime"
Threshold References (Section 5.4)
Purpose: EARS documents REFERENCE thresholds defined in PRD threshold registry. All quantitative values must use @threshold: tags.
Threshold Naming Convention: @threshold: PRD.NN.category.subcategory.key
Example Usage:
WHEN [trigger condition], THE [system component] SHALL [action] WITHIN @threshold: PRD.035.timeout.request.sync.
Common Threshold Categories:
timing: - "@threshold: PRD.NN.timeout.request.sync" - "@threshold: PRD.NN.timeout.connection.default"
performance: - "@threshold: PRD.NN.perf.api.p95_latency" - "@threshold: PRD.NN.perf.batch.max_duration"
limits: - "@threshold: PRD.NN.limit.api.requests_per_second"
error: - "@threshold: PRD.NN.sla.error_rate.target"
Tag Format Convention Notation Format Artifacts Purpose Dash TYPE-NN ADR, SPEC, CTR Technical artifacts - document references Dot TYPE.NN.TT.SS BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS Hierarchical artifacts - element references Cumulative Tagging Requirements
Layer 3 (EARS): Must include tags from Layers 1-2 (BRD, PRD)
Tag Count: 2 tags (@brd, @prd)
Format:
Traceability
Required Tags (Cumulative Tagging Hierarchy - Layer 3): ```markdown @brd: BRD.01.01.03, BRD.01.01.10 @prd: PRD.01.07.02, PRD.01.07.15
Traceability Tag Separators (E041)
Inline format - Use pipes: ```markdown Traceability: @brd: BRD.02.01.10 | @prd: PRD.02.01.01 | @threshold: PRD.035.key
List format - Also valid:
Traceability: - @brd: BRD.02.01.10 - @prd: PRD.02.01.01 - @threshold: PRD.035.category.key
Downstream Artifact References (E045)
CRITICAL: Do NOT use numeric downstream references until artifacts exist.
INVALID - Numeric references to non-existent artifacts
Downstream: BDD-01, ADR-02, REQ-03
VALID - Generic downstream names
Downstream: BDD, ADR, SYS, REQ, SPEC
File Size Limits and Splitting
Limits:
Target: 300-500 lines per file Maximum: 600 lines per file (absolute)
When to Split:
Document approaches 600 lines Sections cover distinct capability areas
Splitting Process:
Create EARS-{NN}.0_index.md using EARS-SECTION-0-TEMPLATE.md Create section files EARS-{NN}.{S}_{slug}.md using EARS-SECTION-TEMPLATE.md Maintain Prev/Next links Update traceability Reserved ID Exemption
Pattern: EARS-00_*.md
Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.
Document Types:
Index documents (EARS-00_index.md) Traceability matrix templates (EARS-00_TRACEABILITY_MATRIX-TEMPLATE.md) Glossaries, registries, checklists Creation Process Step 1: Read Upstream Artifacts
Read and understand BRD and PRD that drive these formal requirements.
Step 2: Reserve ID Number
Check docs/EARS/ for next available ID number (e.g., EARS-01, EARS-02).
ID Numbering Convention: Start with 2 digits and expand only as needed.
✅ Correct: EARS-01, EARS-99, EARS-102 ❌ Incorrect: EARS-001, EARS-009 (extra leading zero not required) Step 3: Create EARS File
Location: docs/EARS/EARS-NN_{slug}.md
Example: docs/EARS/EARS-01_risk_limits.md
Step 4: Fill Document Control Section
Complete all required metadata fields:
Status Version Dates Priority Source Document (single @prd: PRD.NN.EE.SS) BDD-Ready Score Step 5: Categorize Requirements
Group requirements into 4 categories:
Event-Driven (triggered by events) State-Driven (triggered by system state) Unwanted Behavior (preventive) Ubiquitous (always active) Step 6: Write WHEN-THE-SHALL-WITHIN Statements
For each requirement:
Use formal EARS syntax Specify quantifiable constraints with @threshold tags Use SHALL/SHOULD/MAY keywords correctly Reference upstream PRD features Step 7: Create Quality Attributes Section
Use tabular format for Performance, Security, Reliability requirements.
Step 8: Add Cumulative Tags
Include @brd and @prd tags (Layers 1-2) in Traceability section.
Step 9: Add Threshold References
Document all thresholds used in section 5.4.
Step 10: Create/Update Traceability Matrix
MANDATORY: Create or update docs/EARS/EARS-00_TRACEABILITY_MATRIX.md
Step 11: Validate EARS
Run validation scripts:
EARS validation
python scripts/validate_ears.py --path docs/EARS/EARS-01_*.md
Cumulative tagging validation
python ai_dev_flow/scripts/validate_tags_against_docs.py \ --artifact EARS-01 \ --expected-layers brd,prd \ --strict
Step 12: Commit Changes
Commit EARS file and traceability matrix together.
Batch Creation Checkpoint Rules Pre-Batch Verification
Before starting batch creation:
Read EARS_SCHEMA.yaml for current metadata requirements Verify tag standards: ears (not ears-requirements) Verify document_type: ears Verify architecture format: architecture_approaches: [value] (array) Every 5-Document Checkpoint
After creating every 5 EARS documents:
Run validation: python scripts/validate_ears.py --path docs/EARS Check for tag consistency, document_type, Source Document format Fix any errors before continuing End-of-Session Validation
Before ending session:
Run full validation: python scripts/validate_ears.py Verify 0 errors Update EARS-00_index.md if document counts changed Validation Validation Error Codes Reference Code Description Severity E001 YAML frontmatter invalid ERROR E002 Required tags missing (ears, layer-3-artifact) ERROR E003 Forbidden tag patterns (ears-requirements, etc.) ERROR E004 Missing custom_fields ERROR E005 document_type not 'ears' ERROR E006 artifact_type not 'EARS' ERROR E007 layer not 3 ERROR E008 architecture_approaches not array ERROR E010 Required sections missing ERROR E011 Section numbering starts with 0 ERROR E013 Document Control not in table format ERROR E020 Malformed table syntax ERROR E030 Requirement ID format invalid ERROR E040 Source Document missing @prd: prefix ERROR E041 Traceability tags missing pipe separators ERROR E042 Duplicate requirement IDs ERROR E044 Source Document has multiple @prd values ERROR E045 Numeric downstream references ERROR Manual Checklist Document Control section uses table format All required metadata fields completed Source Document has single @prd: PRD.NN.EE.SS value All statements use WHEN-THE-SHALL-WITHIN format Requirements categorized (Event, State, Unwanted, Ubiquitous) Element IDs use EARS.NN.25.SS format SHALL/SHOULD/MAY keywords used correctly Quantifiable constraints with @threshold tags No ambiguous terms ("fast", "efficient") Cumulative tags: @brd, @prd included Traceability tags use pipe separators No numeric downstream references Quality Attributes in tabular format Thresholds documented in section 5.4 File size <600 lines Common Pitfalls Mistake Correction ears-requirements tag Use ears document_type: engineering-requirements Use document_type: ears architecture_approach: value Use architecture_approaches: [value]
Event-001: Title Use #### EARS.01.25.01: Title
Source Document: PRD-NN Use Source Document: @prd: PRD.NN.EE.SS Multiple @prd in Source Document Use single @prd, list others in Upstream Sources @brd: X @prd: Y (no separators) Use @brd: X | @prd: Y Downstream: BDD-01, ADR-02 Use Downstream: BDD, ADR Status: Approved (with 50% score) Use Status: Draft
0. Document Control Use ## Document Control (no numbering)
Post-Creation Validation (MANDATORY)
CRITICAL: Execute validation loop IMMEDIATELY after document creation.
Automatic Validation Loop LOOP: 1. Run: python scripts/validate_ears.py --path {doc_path} 2. IF errors fixed: GOTO LOOP (re-validate) 3. IF warnings fixed: GOTO LOOP (re-validate) 4. IF unfixable issues: Log for manual review 5. IF clean: Mark VALIDATED, proceed
Quality Gate
Blocking: YES - Cannot proceed to BDD creation until validation passes with 0 errors.
Next Skill
After creating EARS, use:
doc-bdd - Create BDD test scenarios (Layer 4)
The BDD will:
Reference this EARS as upstream source Include @brd, @prd, @ears tags (cumulative) Use Gherkin Given-When-Then format Validate EARS formal requirements with executable tests Related Resources Template: ai_dev_flow/EARS/EARS-TEMPLATE.md (Template Version 3.0, primary authority) Schema: ai_dev_flow/EARS/EARS_SCHEMA.yaml (machine-readable validation) Creation Rules: ai_dev_flow/EARS/EARS_CREATION_RULES.md Validation Rules: ai_dev_flow/EARS/EARS_VALIDATION_RULES.md Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md ID Standards: ai_dev_flow/ID_NAMING_STANDARDS.md Threshold Naming: ai_dev_flow/THRESHOLD_NAMING_RULES.md
Section Templates (for documents >300 lines):
Index template: ai_dev_flow/EARS/EARS-SECTION-0-TEMPLATE.md Content template: ai_dev_flow/EARS/EARS-SECTION-TEMPLATE.md Quick Reference Item Value Purpose Formalize requirements with WHEN-THE-SHALL-WITHIN syntax Layer 3 Tags Required @brd, @prd (2 tags) BDD-Ready Score ≥90% required for "Approved" status Element ID Format EARS.NN.25.SS (4-segment unified format) Source Document Single @prd: PRD.NN.EE.SS value Downstream References Generic names only (no numeric IDs) File Size Limit 600 lines maximum Next Skill doc-bdd