doc-ears-audit_skill

Overview

This skill runs a unified EARS audit workflow that executes the structural validator then the semantic reviewer and emits one combined audit report optimized for automatic fixing. It simplifies QA by providing a single command and a normalized output format consumable by doc-ears-fixer. The wrapper preserves separation of concerns while delivering a clear pass/fail status and a prioritized fix queue.

How this skill works

The wrapper first invokes the doc-ears-validator to check schema and template compliance, then runs doc-ears-reviewer to score content quality and testability. Findings from both tools are normalized, merged, and deduplicated into a single combined report with a standardized fix queue. The report includes a deduction-based score, coverage summaries, and actionable fix items annotated with source, severity, file, section, action_hint, and confidence.

When to use it

• When you want one command to run both structural and semantic EARS checks
• When you need a single combined report formatted for doc-ears-fixer consumption
• Before BDD generation to ensure EARS files are high quality and testable
• When you want to automate a fix cycle for auto-fixable issues
• Avoid using when EARS files are not present or when only one domain check is required

Best practices

• Provide the EARS path using the repository-relative docs/03_EARS location
• Use the default reviewer threshold (90) or tune for stricter/looser gates
• Inspect the combined report summary and fix queue before auto-applying fixes
• Treat 'blocking' or 'manual-required' items as highest priority for human review
• Keep EARS files in the expected structure so validator findings are precise

Example use cases

• Run a pre-merge quality gate that enforces schema and content quality with a single command
• Generate a combined audit for doc-ears-fixer to automatically remediate low-risk issues
• Run QA on a batch of EARS files before generating BDD assets
• Produce traceability and coverage summaries for compliance or handoff meetings
• Quickly identify whether an EARS file needs manual edits or can be auto-fixed