doc-brd-audit_skill

Overview

This skill runs a single BRD audit workflow that executes a structural validator then a semantic reviewer and emits one combined audit report optimized for an automated fixer. It provides a clear pass/fail gate and a normalized fix queue so fix automation or manual triage can proceed reliably. Use it to simplify BRD quality checks in CI or pre-PR validation.

How this skill works

The skill runs doc-brd-validator first to check schema and template compliance, then doc-brd-reviewer to score content quality and alignment. Findings from both tools are normalized, merged, and formatted into a single BRD-NN.A_audit_report_vNNN.md containing summary, score calculation, validator and reviewer findings, diagram contract results, and a fix queue. If auto-fixable items exist, it can hand off the combined report to doc-brd-fixer.

When to use it

• You want a single user-facing command to run BRD quality gates
• You need a combined report as input to doc-brd-fixer
• Running CI or manual QA before PRD generation
• Validate both structure and content together before stakeholder review
• You need standardized fix metadata for automation

Best practices

• Run against the canonical BRD path (docs/01_BRD/BRD-NN_*/...) to ensure links and sections resolve
• Use the default reviewer threshold (90) or set a project-specific threshold explicitly
• Enable diagram contract checks when diagrams are required; use strict mode only when agreed across the team
• Ensure BRD files include recommended tags (e.g., @diagram: c4-l1, dfd-l0) and intent headers for better findings
• Review the Fix Queue output fields (source, code, severity, action_hint, confidence) before auto-fixing

Example use cases

• CI pipeline step that gates PRs containing BRD changes and blocks merges on FAIL
• Pre-release QA to produce a combined audit report for engineers and product owners
• Automated fix cycle: run audit, then hand report to doc-brd-fixer to apply auto_fixable fixes
• Manual triage: generate a single report for reviewers to assign follow-up work
• Project onboarding: validate a legacy BRD and generate a prioritized fix queue