doc-brd-audit（BRD 审核文件）

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.

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

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

Validation Tiers (from validate_brd_wrapper.sh)

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

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

1. ## 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)

1. ## Metadata Validation Findings

- deliverable_type presence and validity - document_type correctness - Other required metadata fields

1. ## Script Findings

- Findings from shell validation scripts - List by severity/code

1. ## Claude Review Findings

- Findings from Claude content quality review - List by severity/code

1. ## Diagram Contract Findings

- Required BRD tags status (c4-l1, dfd-l0) - Sequence contract status when sequence is present - Intent header completeness status

1. ## Fix Queue for doc-brd-fixer

- auto_fixable - manual_required - blocked

1. ## 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