Doc Ears

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:

1. List existing upstream artifacts:

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

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn't exist

4. NEVER use placeholders like BRD-XXX or TBD

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

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:

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

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:

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

Category ID Ranges:

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

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

Quality Attribute Categories

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

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:

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

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:

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:

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

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

Validation Error Codes Reference

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

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