doc-ears-reviewer_skill

Overview

This skill performs comprehensive content review and quality assurance for EARS (Easy Approach to Requirements Syntax) documents. It validates folder structure, requirement syntax, threshold quantification, PRD traceability, and testability. The reviewer outputs a scored report, an issue list, and updates a mandatory upstream drift cache.

How this skill works

The reviewer loads EARS files (single or sectioned), enforces nested-folder structure, and runs layered checks: EARS syntax, thresholds, PRD alignment, testability, placeholders, section completeness, naming, and upstream drift detection. Auto-fixable structural issues are applied automatically; content issues are flagged for manual remediation. A review score is calculated and a versioned report and drift cache are written alongside the EARS file.

When to use it

• Immediately after EARS generation (post-autopilot)
• After manual edits to EARS documents
• Before running BDD generation or doc-bdd-autopilot
• As a periodic QA gate in CI/CD documentation pipelines
• When verifying PRD traceability and upstream freshness

Best practices

• Run only after structure validation (nested folders required)
• Keep PRD references (@prd/@ref) accurate to enable drift detection
• Quantify all timing/performance thresholds (WITHIN clauses with units)
• Mark deferred items explicitly; avoid placeholders like [TODO]/[TBD]
• Persist and review the drift cache with every run to detect upstream changes

Example use cases

• Final QA pass before BDD generation to ensure requirements are testable and traceable
• Automated review step in a docs CI pipeline to block regressions from upstream PRD edits
• Reviewing a manually edited EARS file to catch ambiguous subjects and missing thresholds
• Generating a versioned review report and updated drift cache after a review
• Flagging orphaned EARS requirements that lack PRD mapping for manual triage