doc-ears

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)

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

```bash

ls docs/BRD/ docs/PRD/ docs/EARS/ 2>/dev/null

```

1. Reference only existing documents in traceability tags
2. Use null only when upstream artifact type genuinely doesn't exist
3. NEVER use placeholders like BRD-XXX or TBD
4. Do NOT create missing upstream artifacts - skip functionality instead

Before creating EARS, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream BRD and PRD: Read the BRD and PRD that drive this EARS
3. Template: ai_dev_flow/EARS/EARS-TEMPLATE.md (Template Version 3.0, primary authority)
4. Schema: ai_dev_flow/EARS/EARS_SCHEMA.yaml (machine-readable validation rules)
5. Creation Rules: ai_dev_flow/EARS/EARS_CREATION_RULES.md
6. Validation Rules: ai_dev_flow/EARS/EARS_VALIDATION_RULES.md

Template Binding (CRITICAL)

Always use these exact metadata values:

```yaml

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

```

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

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

```markdown

# 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 |

```

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

```

2. State-Driven Requirements

WHILE [system state] THE [system] SHALL [behavior] WITHIN [constraint]

```

WHILE [state condition],

THE [system component] SHALL [continuous behavior]

WITHIN [operational context].

```

3. 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].

```

4. 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:

````markdown

#### 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

````

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

Purpose: Measures EARS maturity and readiness for BDD progression.

Format in Document Control:

```markdown

| 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.

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 |

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"

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:

```yaml

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"

```

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

Layer 3 (EARS): Must include tags from Layers 1-2 (BRD, PRD)

Tag Count: 2 tags (@brd, @prd)

Format:

```markdown

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:

```markdown

Traceability:

• @brd: BRD.02.01.10
• @prd: PRD.02.01.01
• @threshold: PRD.035.category.key

```

CRITICAL: Do NOT use numeric downstream references until artifacts exist.

```markdown

# INVALID - Numeric references to non-existent artifacts

Downstream: BDD-01, ADR-02, REQ-03

# VALID - Generic downstream names

Downstream: BDD, ADR, SYS, REQ, SPEC

```

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:

1. Create EARS-{NN}.0_index.md using EARS-SECTION-0-TEMPLATE.md
2. Create section files EARS-{NN}.{S}_{slug}.md using EARS-SECTION-TEMPLATE.md
3. Maintain Prev/Next links
4. Update traceability

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

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:

1. Event-Driven (triggered by events)
2. State-Driven (triggered by system state)
3. Unwanted Behavior (preventive)
4. 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:

```bash

# 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.

Pre-Batch Verification

Before starting batch creation:

1. Read EARS_SCHEMA.yaml for current metadata requirements
2. Verify tag standards: ears (not ears-requirements)
3. Verify document_type: ears
4. Verify architecture format: architecture_approaches: [value] (array)

Every 5-Document Checkpoint

After creating every 5 EARS documents:

1. Run validation: python scripts/validate_ears.py --path docs/EARS
2. Check for tag consistency, document_type, Source Document format
3. Fix any errors before continuing

End-of-Session Validation

Before ending session:

1. Run full validation: python scripts/validate_ears.py
2. Verify 0 errors
3. Update EARS-00_index.md if document counts changed

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

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

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.

---

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

• 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

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