doc-ears-reviewer

Purpose

Comprehensive content review and quality assurance for EARS (Easy Approach to Requirements Syntax) documents. This skill performs deep content analysis beyond structural validation, checking requirement syntax correctness, PRD alignment, testability, quantifiable thresholds, and identifying issues that require manual review.

Layer: 3 (EARS Quality Assurance)

Upstream: EARS (from doc-ears-autopilot or doc-ears)

Downstream: None (final QA gate before BDD generation)

When to Use This Skill

Use doc-ears-reviewer when:

• After EARS Generation: Run immediately after doc-ears-autopilot completes
• Manual EARS Edits: After making manual changes to EARS
• Pre-BDD Check: Before running doc-bdd-autopilot
• Periodic Review: Regular quality checks on existing EARS
• CI/CD Integration: Automated review gate in documentation pipelines

Do NOT use when:

• EARS does not exist yet (use doc-ears or doc-ears-autopilot first)
• Need structural/schema validation only (use doc-ears-validator)
• Generating new EARS content (use doc-ears)

Skill vs Validator: Key Differences

Review Workflow

flowchart TD
    A[Input: EARS Path] --> B[Load EARS Files]
    B --> C{Sectioned or Monolithic?}

    C -->|Sectioned| D[Load All Section Files]
    C -->|Monolithic| E[Load Single File]

    D --> F[Run Review Checks]
    E --> F

    subgraph Review["Review Checks"]
        F --> F0[0. Structure Compliance]
        F0 --> G[1. EARS Syntax Compliance]
        G --> H[2. Threshold Quantification]
        H --> I[3. PRD Alignment]
        I --> J[4. Testability Assessment]
        J --> K[5. Placeholder Detection]
        K --> L[6. Section Completeness]
        L --> M[7. Naming Compliance]
        M --> M2[8. Upstream Drift Detection]
    end

    M2 --> N{Issues Found?}
    N -->|Yes| O[Categorize Issues]
    O --> P{Auto-Fixable?}
    P -->|Yes| Q[Apply Auto-Fixes]
    Q --> R[Re-run Affected Checks]
    P -->|No| S[Flag for Manual Review]
    R --> N
    S --> T[Generate Report]
    N -->|No| T
    T --> U[Calculate Review Score]
    U --> V{Score >= Threshold?}
    V -->|Yes| W[PASS]
    V -->|No| X[FAIL with Details]

Review Checks

0. Structure Compliance (12/12) – BLOCKING

Validates EARS follows the mandatory nested folder rule.

Nested Folder Rule: ALL EARS documents MUST be in nested folders.

Required Structure:

Detection:

Validating folder structure...
├── EARS Location: docs/03_EARS/EARS-01_f1_iam/EARS-01_f1_iam.md
├── Expected Folder: EARS-01_f1_iam ✓
├── Parent Path: docs/03_EARS/ ✓
├── Nested Structure: Valid ✓
└── Result: PASS

Error Codes:

This check is BLOCKING – EARS must pass structure validation before other checks proceed.

1. EARS Syntax Compliance

Validates all requirements follow correct EARS patterns.

EARS Patterns:

• Ubiquitous: THE {system} SHALL {action}
• Event-Driven: WHEN {event} THE {system} SHALL {action}
• State-Driven: WHILE {state} THE {system} SHALL {action}
• Optional: WHERE {feature} THE {system} SHALL {action}
• Complex: WHEN {event} WHILE {state} THE {system} SHALL {action}
• Unwanted: IF {condition} THEN THE {system} SHALL {action} WITHIN {time}

Error Codes:

2. Threshold Quantification

Validates all timing/performance thresholds are specific.

Scope:

• WITHIN clauses have numeric values
• Units specified (ms, s, min)
• Consistent with PRD thresholds
• No vague terms (“quickly”, “fast”, “responsive”)

Error Codes:

3. PRD Alignment

Validates EARS requirements trace to PRD source.

Scope:

• Every EARS requirement maps to PRD requirement
• No orphaned requirements
• No missing requirements (PRD without EARS)
• Feature IDs consistent

Error Codes:

4. Testability Assessment

Evaluates if requirements can be tested.

Scope:

• Measurable outcomes defined
• Pass/fail criteria clear
• Edge cases identified
• Negative cases covered

Error Codes:

5. Placeholder Detection

Identifies incomplete content requiring replacement.

Error Codes:

6. Section Completeness

Verifies all required sections have substantive content.

Error Codes:

7. Naming Compliance

Validates element IDs follow doc-naming standards.

Scope:

• Element IDs use EARS.NN.TT.SS format
• Element type codes valid for EARS (25, 26)
• No legacy patterns (REQ-NNN, R-NNN)

Error Codes:

8. Upstream Drift Detection (Mandatory Cache)

Detects when upstream source documents have been modified after the EARS was created or last updated.

The drift cache is mandatory – the reviewer MUST create/update it after every review.

Purpose: Identifies stale EARS content that may not reflect current PRD documentation.

Scope:

• @ref: tag targets
• @prd: tag references
• Traceability section upstream artifact links

8.1 Drift Cache File (MANDATORY)

Location: docs/03_EARS/.drift_cache.json

Schema:

{
  "cache_version": "1.0",
  "artifact_type": "EARS",
  "upstream_type": "PRD",
  "last_updated": "2026-02-10T17:00:00Z",
  "entries": {
    "EARS-01": {
      "ears_file": "docs/03_EARS/EARS-01_f1_iam.md",
      "ears_hash": "sha256:abc123...",
      "ears_mtime": "2026-02-10T15:00:00Z",
      "upstream_refs": [
        {
          "prd_id": "PRD-01",
          "prd_file": "docs/02_PRD/PRD-01_f1_iam.md",
          "prd_hash": "sha256:def456...",
          "prd_mtime": "2026-02-10T14:00:00Z",
          "prd_version": "1.2"
        }
      ],
      "last_review": "2026-02-10T16:00:00Z",
      "drift_status": "clean"
    }
  }
}

8.2 Detection Algorithm (Three-Phase)

Phase 1: Load Cache

IF cache file exists:
    Load existing cache
    Validate cache schema
ELSE:
    Initialize empty cache
    Mark as first review (REV-D006)

Phase 2: Detect Drift

FOR each EARS document:
    Calculate current EARS hash
    FOR each upstream PRD reference:
        Calculate current PRD hash
        IF cache entry exists:
            Compare PRD hash with cached hash
            IF hashes differ:
                Flag drift (REV-D001/D002/D005)
            Compare PRD mtime with cached mtime
            IF mtime newer:
                Flag potential drift (REV-D003)
        ELSE:
            New reference - no drift comparison possible

Phase 3: Update Cache (MANDATORY)

FOR each reviewed EARS document:
    Update EARS hash and mtime
    FOR each upstream PRD reference:
        Update PRD hash, mtime, and version
    Set drift_status based on review results
    Set last_review to current timestamp
Write updated cache to disk

8.3 Hash Calculation (MANDATORY BASH EXECUTION)

CRITICAL: You MUST execute actual bash commands to compute hashes. DO NOT write placeholder values.

Compute File Hash:

sha256sum <file_path> | cut -d' ' -f1

Store result as: "hash": "sha256:<64_hex_characters>"

REJECTED VALUES (re-compute immediately):

• sha256:verified_no_drift
• sha256:pending_verification
• Any value where hex portion != 64 characters

Verification:

grep -oP '"hash":\s*"sha256:[0-9a-f]{64}"' .drift_cache.json

Error Codes:

8.5 Report Output

The review report MUST include cache status:

## Upstream Drift Detection

**Cache Status**: Updated | Created | Error
**Cache Location**: `docs/03_EARS/.drift_cache.json`

| EARS | Upstream PRD | Drift Status | Last Verified |
|------|--------------|--------------|---------------|
| EARS-01 | PRD-01 | Clean | 2026-02-10T17:00:00Z |
| EARS-02 | PRD-02 | Drift Detected (REV-D002) | 2026-02-10T17:00:00Z |

Configuration:

Review Score Calculation

Scoring Formula:

Total: Sum of all categories (max 100)

Thresholds:

• PASS: ≥ 90
• WARNING: 80-89
• FAIL: < 80

Command Usage

# Review specific EARS
/doc-ears-reviewer EARS-01

# Review EARS by path
/doc-ears-reviewer docs/03_EARS/EARS-01_f1_iam.md

# Review all EARS
/doc-ears-reviewer all

Output Report

Review reports are stored alongside the reviewed document per project standards.

Nested Folder Rule: ALL EARS use nested folders (EARS-NN_{slug}/) regardless of size. This ensures review reports, fix reports, and drift cache files are organized with their parent document.

Audit Wrapper Note: doc-ears-audit combines this reviewer output with validator findings and writes EARS-NN.A_audit_report_vNNN.md (preferred for fixer). Reviewer-native report naming remains EARS-NN.R_review_report_vNNN.md.

File Naming: EARS-NN.R_review_report_vNNN.md

Location: Inside the EARS nested folder: docs/03_EARS/EARS-NN_{slug}/

Versioning Rules

1. First Review: Creates EARS-NN.R_review_report_v001.md
2. Subsequent Reviews: Auto-increments version (v002, v003, etc.)
3. Same-Day Reviews: Each review gets unique version number

Version Detection: Scans folder for existing EARS-NN.R_review_report_v*.md files and increments.

Example:

docs/03_EARS/EARS-01_f1_iam/
├── EARS-01_f1_iam.md
├── EARS-01.R_review_report_v001.md    # First review
├── EARS-01.R_review_report_v002.md    # After fixes
└── .drift_cache.json

Delta Reporting

When previous reviews exist, include score comparison in the report.

See REVIEW_DOCUMENT_STANDARDS.md for complete versioning requirements.

Integration with doc-ears-autopilot

This skill is invoked during Phase 5 of doc-ears-autopilot:

flowchart LR
    A[Phase 4: Validation] --> B[Phase 5: Final Review]
    B --> C{doc-ears-reviewer}
    C --> D[Phase 6: Continue]

Related Skills

Version History