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:

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

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)

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, IPLAN	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:

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-000_*.md

Scope: Documents with reserved ID 000 are FULLY EXEMPT from validation.

Document Types:

• Index documents (EARS-000_index.md)
• Traceability matrix templates (EARS-000_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).

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