doc-brd-audit

Purpose

Run a single BRD audit workflow that executes:

1. doc-brd-validator (structural/schema gate)
2. doc-brd-reviewer (semantic/content quality gate)

Then emit one combined report optimized for doc-brd-fixer input.

Layer: 1 (BRD Quality Gate Wrapper)

Upstream: BRD file(s)

Downstream:

• Combined Audit Report: BRD-NN.A_audit_report_vNNN.md
• Optional Fix Cycle trigger for doc-brd-fixer

Why This Skill Exists

Use this wrapper to avoid user confusion between validator and reviewer while preserving separation of concerns.

When to Use

Use doc-brd-audit when:

• You want one command for BRD quality checks
• You need a combined report for doc-brd-fixer
• You are running CI/manual QA before PRD generation

Do NOT use when:

• BRD does not exist (use doc-brd / doc-brd-autopilot generation first)
• You only need one specific check domain (use validator or reviewer directly)

Execution Contract

Input

• BRD path (docs/01_BRD/BRD-NN_*/...)
• Optional: threshold (default review threshold: 90)

Sequence (Mandatory)

1) Run doc-brd-validator
2) Run doc-brd-reviewer
3) Normalize and merge findings
4) Write BRD-NN.A_audit_report_vNNN.md
5) If auto-fixable findings exist, hand off to doc-brd-fixer

Combined Status Rules

• PASS: Validator PASS AND Reviewer score >= threshold AND no blocking issues
• FAIL: Validator FAIL OR Reviewer score < threshold OR blocking/manual-required issues present

Diagram Contract Gate (ADVISORY for BRD):

• BRD diagram findings are recorded as non-blocking by default.
• Recommended tags: @diagram: c4-l1 and @diagram: dfd-l0
• If sequence diagram exists, recommend one sequence tag (@diagram: sequence-sync|sequence-async|sequence-error)
• Recommended intent fields: diagram_type, level, scope_boundary, upstream_refs, downstream_refs
• Optional strict mode only when explicitly enabled (e.g., audit_strict_diagrams: true).

Combined Report Format (for doc-brd-fixer)

Output file: BRD-NN.A_audit_report_vNNN.md

Required sections:

1. ## Summary
   • BRD ID, timestamp (EST), overall status
   • Validator status, reviewer score
2. ## Score Calculation (Deduction-Based)
   • Formula: 100 - total_deductions
   • Deductions grouped by: contamination (max 50), FR completeness (max 30), structure/quality (max 20)
   • Threshold comparison (>=90 pass gate)
3. ## Validator Findings
   • List by severity/code
4. ## Reviewer Findings
   • List by severity/code
5. ## Diagram Contract Findings
   • Required BRD tags status (c4-l1, dfd-l0)
   • Sequence contract status when sequence is present
   • Intent header completeness status
6. ## Fix Queue for doc-brd-fixer
   • auto_fixable
   • manual_required
   • blocked
7. ## Recommended Next Step
   • run doc-brd-fixer
   • or manual update required

Fix Queue Normalization

Each finding MUST include:

• source: validator | reviewer
• code: issue code
• severity: error|warning|info
• file: relative path
• section: heading/anchor if known
• action_hint: short imperative guidance
• confidence: high|medium|manual-required

Hand-off Contract to doc-brd-fixer

doc-brd-fixer MUST accept combined audit report as equivalent upstream input:

• BRD-NN.A_audit_report_vNNN.md
• BRD-NN.R_review_report_vNNN.md (legacy compatibility)

If both exist, fixer should prefer latest timestamp.

Example Invocation

/doc-brd-audit docs/01_BRD/BRD-01_platform/BRD-01_platform.md

Expected outcome:

1. validator runs
2. reviewer runs
3. combined audit report generated
4. fixer can execute directly from combined report

Version History