doc-bdd-audit_skill

Overview

This skill provides a unified BDD audit wrapper that runs a structural validator and a semantic reviewer, then emits a single combined report optimized for automatic fixing. It simplifies BDD quality checks by presenting one command and one report that downstream tools (like doc-bdd-fixer) can consume. The wrapper preserves separation of concerns while reducing user confusion between validator and reviewer outputs.

How this skill works

The wrapper executes doc-bdd-validator first to enforce schema and template rules, then runs doc-bdd-reviewer to assess content quality and scenario completeness. Findings from both tools are normalized, merged, and scored with a deduction-based formula to produce a single audit report (BDD-NN.A_audit_report_vNNN.md). If auto-fixable issues are present, the report includes a fix queue and can trigger doc-bdd-fixer.

When to use it

• When you want one command to run both structural and semantic BDD checks
• When you need a combined report formatted for doc-bdd-fixer input
• Before ADR generation to ensure BDD quality gates are met
• When you want consistent pass/fail semantics across validator and reviewer results
• Not for initial BDD creation — run after BDD files exist and are committed

Best practices

• Run against the BDD directory path (e.g., docs/04_BDD/BDD-01_f1_iam/) rather than individual files for consistent reports
• Keep the reviewer threshold at the default 90 unless project policy dictates otherwise
• Review the Fix Queue section to decide between automated fixes and manual updates
• Ensure timestamps and filenames follow the audit report naming convention for fixer compatibility
• Treat validator findings as blocking until resolved to avoid false positives in overall status

Example use cases

• CI job that runs BDD quality gate before merging feature branches
• Pre-ADR QA step that ensures scenario completeness and schema compliance
• Nightly audit that produces combined reports for the fixer to consume automatically
• Manual quality audit when preparing a release to surface blocking issues and auto-fix candidates