Skills
skills/vladm3105/aidoc-flow-framework/doc-brd-audit

doc-brd-audit

SKILL.md

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:

  1. ## Summary
    • BRD ID, timestamp (EST), overall status
    • Script validation status, Claude review 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. ## Metadata Validation Findings
    • deliverable_type presence and validity
    • document_type correctness
    • Other required metadata fields
  4. ## Script Findings
    • Findings from shell validation scripts
    • List by severity/code
  5. ## Claude Review Findings
    • Findings from Claude content quality review
    • List by severity/code
  6. ## Diagram Contract Findings
    • Required BRD tags status (c4-l1, dfd-l0)
    • Sequence contract status when sequence is present
    • Intent header completeness status
  7. ## Fix Queue for doc-brd-fixer
    • auto_fixable
    • manual_required
    • blocked
  8. ## 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:

  1. Shell validation scripts run (same as pre-commit)
  2. Claude content quality review runs
  3. Combined audit report generated: BRD-01.A_audit_report_vNNN.md
  4. 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
Weekly Installs
20
Repository
vladm3105/aidoc…ramework
GitHub Stars
9
First Seen
Feb 27, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
opencode20
gemini-cli20
github-copilot20
amp20
cline20
codex20