doc-brd-audit

MANUAL USE ONLY - This skill is for interactive use, not pre-commit. Pre-commit runs shell scripts directly without Claude.

Purpose

Run a unified BRD audit workflow that combines shell script validation and Claude content review into a single pass, producing one combined report optimized for doc-brd-fixer input.

Architecture: Shell scripts for structural validation + Claude for content quality review.

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

The 2-skill model (doc-brd-audit

• doc-brd-fixer ) simplifies the BRD quality workflow.

Concern Owner Skill

All validation + scoring doc-brd-audit (this skill)

Apply fixes from audit report doc-brd-fixer

Fresh Audit Policy (MANDATORY)

ALWAYS run the audit from scratch. Do NOT:

• Reference previous audit reports for scoring decisions

• Skip validation steps based on drift cache history

• Assume compliance from prior fix history

• Use cached results from previous runs

ALWAYS:

• Run all validation scripts fresh every time

• Re-check all structure/schema compliance

• Re-compute PRD-ready score independently

• Generate a new audit report with incremented version

Report Cleanup Policy (MANDATORY)

After generating a new audit report, delete all previous reports. Old reports serve no purpose since:

• Fresh Audit Policy means old reports are never reused for scoring

• Only the latest report is used by doc-brd-fixer

• Multiple old reports clutter the BRD folder

Cleanup Rules

File Pattern Action Reason

BRD-NN.A_audit_report_v*.md (older versions) DELETE Superseded by new audit

BRD-NN.R_review_report_v*.md (legacy) DELETE Deprecated format, superseded

BRD-NN.F_fix_report_v*.md

KEEP Fix history may be useful for tracking

.drift_cache.json

KEEP Tracks review history metadata

Cleanup Execution

After writing the new audit report, run:

In the BRD folder (e.g., docs/01_BRD/BRD-50_octo_agent_orchestration/)

BRD_FOLDER="$1" NEW_REPORT="$2" # e.g., BRD-50.A_audit_report_v012.md

Delete old audit reports (keep only the new one)

find "${BRD_FOLDER}" -name "BRD-.A_audit_report_v.md" ! -name "$(basename ${NEW_REPORT})" -delete

Delete legacy review reports (deprecated format)

find "${BRD_FOLDER}" -name "BRD-.R_review_report_v.md" -delete

What Gets Kept

After cleanup, the BRD folder should contain:

docs/01_BRD/BRD-NN_{slug}/ ├── BRD-NN_{slug}.md # Main BRD document ├── BRD-NN.A_audit_report_vNNN.md # Latest audit report (ONLY ONE) ├── BRD-NN.F_fix_report_v*.md # Fix reports (kept for history) └── .drift_cache.json # Drift detection cache

Cleanup Confirmation

The audit report should include a cleanup summary:

Cleanup Summary

• Deleted: 3 old audit reports (v009, v010, v011)
• Deleted: 4 legacy review reports
• Kept: 2 fix reports

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 pre-commit validation scripts (see Script-Based Validation)
2. Parse script output for findings
3. Run content quality review (Claude analysis)
4. Normalize and merge all findings
5. Write BRD-NN.A_audit_report_vNNN.md
6. If auto-fixable findings exist, hand off to doc-brd-fixer

Script-Based Validation (Pre-commit Integration)

This skill MUST invoke the same validation scripts used by pre-commit hooks. This ensures consistency between CI/CD and manual audit runs.

Required Scripts

Script Purpose Exit Codes

validate_brd_wrapper.sh

Core + advisory validation wrapper 0=pass, 2=core fail, 1=advisory fail

validate_standardized_element_codes.py

Element ID format validation 0=pass, non-zero=fail

detect_legacy_element_ids.py

Legacy pattern detection 0=pass, non-zero=warnings

Script Execution

From repository root

REPO_ROOT="$(git rev-parse --show-toplevel)" BRD_PATH="$1" # e.g., docs/01_BRD/BRD-01_platform

1. Run core wrapper (includes structural + quality gate)

bash "${REPO_ROOT}/ai_dev_ssd_flow/01_BRD/scripts/validate_brd_wrapper.sh" "${BRD_PATH}" 2>&1

2. Run standardized element codes (strict mode)

python3 "${REPO_ROOT}/ai_dev_ssd_flow/scripts/validate_standardized_element_codes.py" "${BRD_PATH}" --strict 2>&1

3. Run legacy pattern detection

python3 "${REPO_ROOT}/ai_dev_ssd_flow/scripts/detect_legacy_element_ids.py" "${BRD_PATH}" --summary 2>&1

Script Output Parsing

The skill MUST parse script output to extract findings:

Output Pattern Finding Type Severity

[FAIL]

Blocking issue error

[WARN]

Non-blocking issue warning

[PASS]

Check passed info

ERROR:

Script error error

Line with file path + issue File-specific finding varies

Validation Tiers (from validate_brd_wrapper.sh)

Tier Checks Blocking

Tier 1 (CORE) Standardized element codes, BRD structural validation, BRD quality gate Yes

Tier 2 (ADVISORY) Metadata validation, Link validation, Forward reference validation, Diagram consistency No (default)

Pre-commit vs Skill Separation

Pre-commit hooks run shell scripts directly (no Claude):

.pre-commit-config.yaml - runs on every commit

• id: brd-core-wrapper # validate_brd_wrapper.sh
• id: brd-standardized-element-codes # validate_standardized_element_codes.py
• id: brd-legacy-patterns # detect_legacy_element_ids.py

This skill is for manual/interactive use:

Manual invocation for full audit + report generation

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

Flow:

Automatic (pre-commit): git commit → shell scripts → pass/fail

Manual (skill): /doc-brd-audit → shell scripts → Claude review → audit report

Combined Status Rules

• PASS : Script validation PASS AND Claude review score >= threshold AND no blocking issues

• FAIL : Script validation FAIL OR Claude review 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 ).

Metadata Validation

The audit MUST validate BRD frontmatter metadata compliance.

Required Metadata Fields

Field Type Required Valid Values

document_type

string Yes brd-document

artifact_type

string Yes BRD

layer

integer Yes 1

deliverable_type

string Yes code , document , ux , risk , process

Metadata Validation Rules

VALID-M001: deliverable_type Present

• Severity: Error

• Check: deliverable_type exists in custom_fields

• Fix: Add deliverable_type: code (default)

VALID-M002: deliverable_type Valid Value

• Severity: Error

• Check: deliverable_type is one of: code , document , ux , risk , process

• Fix: Reset to code (default) or suggest based on BRD content

VALID-M003: document_type Correct for Instance

• Severity: Error

• Check: document_type is brd-document (not template )

• Fix: Change to brd-document

Metadata Validation Detection

def validate_deliverable_type(frontmatter: dict) -> list[Finding]: """Validate deliverable_type metadata field.""" findings = [] custom_fields = frontmatter.get('custom_fields', {})

# Check M001: deliverable_type present
if 'deliverable_type' not in custom_fields:
    findings.append({
        'code': 'VALID-M001',
        'severity': 'error',
        'message': 'Missing deliverable_type in custom_fields',
        'fix_action': 'Add deliverable_type: code',
        'confidence': 'auto-safe'
    })
    return findings

# Check M002: valid value
deliverable_type = custom_fields['deliverable_type']
valid_values = ['code', 'document', 'ux', 'risk', 'process']

if deliverable_type not in valid_values:
    findings.append({
        'code': 'VALID-M002',
        'severity': 'error',
        'message': f'Invalid deliverable_type: {deliverable_type}',
        'valid_values': valid_values,
        'fix_action': f'Change to one of: {", ".join(valid_values)}',
        'confidence': 'auto-assisted'  # May need content analysis
    })

return findings

Combined Report Format (for doc-brd-fixer)

Output file: BRD-NN.A_audit_report_vNNN.md

Required sections:

• Summary

• BRD ID, timestamp (EST), overall status

• Script validation status, Claude review score

• 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)

• Metadata Validation Findings

• deliverable_type presence and validity

• document_type correctness

• Other required metadata fields

• Script Findings

• Findings from shell validation scripts

• List by severity/code

• Claude Review Findings

• Findings from Claude content quality review

• List by severity/code

• Diagram Contract Findings

• Required BRD tags status (c4-l1 , dfd-l0 )

• Sequence contract status when sequence is present

• Intent header completeness status

• Fix Queue for doc-brd-fixer

• auto_fixable

• manual_required

• blocked

• Recommended Next Step

• run doc-brd-fixer

• or manual update required

Fix Queue Normalization

Each finding MUST include:

• source : script | claude (script = shell validation, claude = content review)

• 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:

• Shell validation scripts run (same as pre-commit)

• Claude content quality review runs

• Combined audit report generated: BRD-01.A_audit_report_vNNN.md

• Fixer can execute directly from combined report

Version History

Version Date Changes

2.4 2026-03-05 Metadata Validation: Added validation for deliverable_type metadata field (VALID-M001, VALID-M002, VALID-M003); Validates presence, valid values (code , document , ux , risk , process ), and document_type correctness; Added "Metadata Validation Findings" section to combined report

2.3 2026-03-05 Report Cleanup Policy: Added mandatory cleanup of old audit reports after generating new one; Deletes previous BRD-NN.A_audit_report_v*.md and legacy BRD-NN.R_review_report_v*.md files; Keeps fix reports and drift cache; Added cleanup summary section to audit report

2.2 2026-03-05 Shell-first approach: Pre-commit runs shell scripts directly (not Claude); Skill is for manual use only; Skill invokes same scripts then adds Claude review; Removed obsolete doc-brd-validator /doc-brd-reviewer references

2.1 2026-03-01 Added Fresh Audit Policy (MANDATORY); All validation and scoring unified in this skill

1.3 2026-02-26 Added advisory BRD C4/DFD/sequence diagram contract checks and required Diagram Contract Findings section in combined audit reports

1.2 2026-02-26 Initial audit wrapper; combined report contract for fixer