doc-brd-reviewer

Purpose

Comprehensive content review and quality assurance for Business Requirements Documents (BRD). This skill performs deep content analysis beyond structural validation, checking link integrity, requirement completeness, ADR topic coverage, strategic alignment, and identifying issues that require manual business review.

Layer: 1 (BRD Quality Assurance)

Upstream: Strategy documents, stakeholder requirements

Downstream: None (final QA gate before PRD generation)

When to Use This Skill

Use doc-brd-reviewer when:

• After BRD Generation: Run immediately after doc-brd-autopilot completes
• Manual BRD Edits: After making manual changes to a BRD
• Pre-PRD Check: Before running doc-prd-autopilot
• Periodic Review: Regular quality checks on existing BRDs
• CI/CD Integration: Automated review gate in documentation pipelines

Do NOT use when:

• BRD does not exist yet (use doc-brd or doc-brd-autopilot first)
• Need structural/schema validation only (use doc-brd-validator)
• Generating new BRD content (use doc-brd)

Skill vs Validator: Key Differences

Review Workflow

flowchart TD
    A[Input: BRD Path] --> B[Load BRD Files]
    B --> C{Sectioned or Monolithic?}

    C -->|Sectioned| D[Load All Section Files]
    C -->|Monolithic| E[Load Single File]

    D --> F0[Check #0: Structure Compliance]
    E --> F0

    F0 --> F0a{Nested Folder Valid?}
    F0a -->|No| F0b[FAIL - BLOCKING]
    F0a -->|Yes| F[Run Review Checks]

    subgraph Review["Review Checks"]
        F --> G[1. Link Integrity]
        G --> H[2. Requirement Completeness]
      H --> H2[2a. Diagram Contract Compliance]
      H2 --> I[3. ADR Topic Coverage]
      I --> J[4. Placeholder Detection]
      J --> K[5. Traceability Tags]
      K --> L[6. Section Completeness]
      L --> M[7. Strategic Alignment]
      M --> M2[8. Naming Compliance]
      M2 --> M3[9. Upstream Drift Detection]
    end

    M3 --> N{Issues Found?}
    N -->|Yes| O[Categorize Issues]
    O --> P{Auto-Fixable?}
    P -->|Yes| Q[Apply Auto-Fixes]
    Q --> R[Re-run Affected Checks]
    P -->|No| S[Flag for Manual Review]
    R --> N
    S --> T[Generate Report]
    N -->|No| T
    T --> U[Calculate Review Score]
    U --> V{Score >= Threshold?}
    V -->|Yes| W[PASS]
    V -->|No| X[FAIL with Details]

Review Checks

0. Structure Compliance (BLOCKING)

Validates BRD follows the mandatory nested folder rule.

Nested Folder Rule: ALL BRDs MUST be in nested folders regardless of size.

Required Structure:

Validation:

1. Check document is inside a nested folder: docs/01_BRD/BRD-NN_{slug}/
2. Verify folder name matches BRD ID pattern: BRD-NN_{slug}
3. Verify file name matches folder: BRD-NN_{slug}.md or BRD-NN.N_*.md
4. Parent path must be: docs/01_BRD/

Example Valid Structure:

docs/01_BRD/
├── BRD-01_f1_iam/
│   ├── BRD-01_f1_iam.md           ✓ Valid (monolithic)
│   ├── BRD-01.R_review_report_v001.md
│   └── .drift_cache.json
├── BRD-02_f2_session/
│   ├── BRD-02.0_index.md          ✓ Valid (sectioned)
│   ├── BRD-02.1_core.md
│   └── BRD-02.2_requirements.md

Invalid Structure:

docs/01_BRD/
├── BRD-01_f1_iam.md               ✗ NOT in nested folder

Auto-Fix:

1. Create the nested folder docs/01_BRD/BRD-NN_{slug}/
2. Move the BRD file(s) into the folder
3. Update all internal links (navigation, cross-references)
4. Update any downstream PRD links to correct path

Error Codes:

This check is BLOCKING – BRD must pass structure validation before other checks proceed.

1. Link Integrity

Validates all internal document links resolve correctly.

Scope:

• Navigation links ([Previous: ...], [Next: ...])
• Section cross-references (for example, See Section 7.2)
• Index to section links
• External documentation links (warns if unreachable)

Error Codes:

2. Requirement Completeness

Validates all business requirements have complete specifications.

Scope:

• Each requirement has acceptance criteria
• Success metrics defined
• Scope boundaries clear (in/out)
• Priority assignments present
• Dependencies documented

Error Codes:

2a. Diagram Contract Compliance

Validates BRD diagram contract requirements defined by ai_dev_ssd_flow/DIAGRAM_STANDARDS.md.

Scope:

• Required BRD tags: @diagram: c4-l1, @diagram: dfd-l0
• Sequence tag presence when sequence diagram is used
• Intent header fields: diagram_type, level, scope_boundary, upstream_refs, downstream_refs
• Trust-boundary annotations when data boundary movement is documented

Error Codes:

3. ADR Topic Coverage

Validates Section 7.2 ADR Topics have complete coverage.

Scope:

• All 7 mandatory categories present (Infrastructure, Data Architecture, Integration, Security, Observability, AI/ML, Technology Selection)
• Each topic has Status, Alternatives Overview, Decision Drivers
• Selected topics have Cloud Provider Comparison table
• Deferred topics have justification

Error Codes:

4. Placeholder Detection

Identifies incomplete content requiring replacement.

Scope:

• [TODO], [TBD], [PLACEHOLDER] text
• Template dates: YYYY-MM-DDTHH:MM:SS, MM/DD/YYYY
• Template names: [Name], [Author], [Reviewer]
• Empty sections: <!-- Content here -->
• Lorem ipsum or sample text

Auto-Fix:

• Replace YYYY-MM-DDTHH:MM:SS with current datetime
• Replace [Name] with document author from metadata
• Remove empty comment placeholders
• Flag [TODO]/[TBD] for manual completion

Error Codes:

5. Traceability Tags

Validates cross-reference tags and element IDs.

Scope:

• @ref: tags reference valid documents (if upstream_mode: “ref”)
• Element IDs properly formatted
• Cross-references consistent
• Traceability section completeness

Error Codes:

6. Section Completeness

Verifies all 18 required sections have substantive content per BRD-MVP-TEMPLATE.

Scope:

• All 18 numbered sections present (plus Document Control)
• Minimum word count per section
• Required subsections for governance, traceability, glossary
• Tables have data rows (not just headers)
• Mermaid diagrams render properly

18-Section Structure Validation:

MVP-Critical Subsections (bold items above):

Error Codes:

6.1 Subsection Validation Algorithm

FOR each section in 18_SECTION_LIST:
  1. Verify section header exists: "## {N}. {Title}"
  2. Count words in section content
  3. IF section has required_subsections:
     FOR each subsection in required_subsections:
       - Search for header pattern: "### {N}.{M}" or "#### {N}.{M}.{X}"
       - IF not found: Add appropriate error code
       - IF found: Validate minimum content (>10 words)
  4. IF section < minimum_words: Add REV-S002 warning

Section Detection Patterns:

Sectioned BRD Handling:

For sectioned BRDs (BRD-NN.N_*.md files):

1. Map file to section number from filename pattern
2. Validate section content within that file
3. Cross-reference section numbering consistency

7. Strategic Alignment

Validates BRD aligns with business strategy and objectives.

Scope:

• Business objectives trace to strategic goals
• Success metrics align with KPIs
• Scope matches project charter
• Stakeholder concerns addressed
• Implementation-derived content is translated into business-language outcomes

Error Codes:

8. Naming Compliance

Validates element IDs follow doc-naming standards.

Scope:

• Element IDs use BRD.NN.TT.SS format
• Element type codes valid for BRD (01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33)
• No legacy patterns (BO-NNN, FR-NNN, etc.)

Auto-Fix:

• Convert legacy patterns to unified format
• Suggest correct element type codes

Error Codes:

9. Upstream Drift Detection (Conditional)

Detects when upstream reference documents have been modified after the BRD was created. This check is CONDITIONAL based on upstream_mode setting.

9.0 Mode Detection (First Step)

Before running drift detection:

1. Read YAML frontmatter custom_fields.upstream_mode
2. Apply behavior:

If skipping:

• Log: INFO: Upstream drift detection skipped (upstream_mode: none)
• Award full 5/5 points
• Create minimal drift cache entry

Scope (when upstream_mode: "ref"):

• Documents in paths specified by upstream_ref_path
• @ref: tag targets within those paths
• Traceability section upstream artifact links
• GAP analysis document references

9.1 Drift Cache File (MANDATORY)

Location: docs/01_BRD/{BRD_folder}/.drift_cache.json

IMPORTANT: The reviewer MUST:

1. Read the cache if it exists (for hash comparison)
2. Create the cache if it doesn’t exist
3. Update the cache after every review with current hashes

Cache Schema (when upstream_mode: "none" or not set):

{
  "schema_version": "1.1",
  "document_id": "BRD-01",
  "document_version": "1.0",
  "upstream_mode": "none",
  "upstream_ref_path": null,
  "drift_detection_skipped": true,
  "skip_reason": "upstream_mode set to none (default)",
  "last_reviewed": "2026-02-24T21:00:00",
  "reviewer_version": "1.6",
  "upstream_documents": {},
  "review_history": [
    {
      "date": "2026-02-24T21:00:00",
      "score": 97,
      "drift_detected": false,
      "report_version": "v001"
    }
  ]
}

Cache Schema (when upstream_mode: "ref"):

{
  "schema_version": "1.1",
  "document_id": "BRD-01",
  "document_version": "1.0",
  "upstream_mode": "ref",
  "upstream_ref_path": ["../../00_REF/source_docs/"],
  "drift_detection_skipped": false,
  "last_reviewed": "2026-02-24T21:00:00",
  "reviewer_version": "1.6",
  "upstream_documents": {
    "../../00_REF/source_docs/BeeLocal_BRD_v2.1.md": {
      "hash": "sha256:c9810281...",
      "last_modified": "2024-12-25T00:00:06",
      "file_size": 76908,
      "version": "2.1",
      "sections_tracked": []
    }
  },
  "review_history": [
    {
      "date": "2026-02-24T21:00:00",
    PRD-Ready Score = 100 - total_deductions
      "drift_detected": false,
      "report_version": "v001"
    }
  ]
}

9.2 Detection Algorithm (Three-Phase)

PHASE 1: Load Cache (if exists)
=========================================
1. Check for .drift_cache.json in BRD folder
2. If exists:
   - Load cached hashes and metadata
   - Set detection_mode = "hash_comparison"
3. If not exists:
   - Set detection_mode = "timestamp_only"
   - Will create cache at end of review

PHASE 2: Detect Drift
=========================================
For each upstream reference in BRD:

  A. Extract reference:
     - @ref: tags → [path, section anchor]
     - @strategy: tags → [document ID]
     - Links to ../00_REF/ → [path]
     - Traceability table upstream artifacts → [path]

  B. Resolve and validate:
     - Resolve path to absolute file path
     - Check file exists (skip if covered by Check #1)
     - Get file stats: mtime, size

  C. Compare (based on detection_mode):

     IF detection_mode == "hash_comparison":
       - Compute SHA-256 hash of current file content
       - Compare to cached hash
       - IF hash differs:
           - Calculate change_percentage
           - Flag as CONTENT_DRIFT (REV-D002)
           - IF change > 20%: Flag as CRITICAL (REV-D005)

     ELSE (timestamp_only):
       - Compare file mtime > BRD last_updated
       - IF mtime > BRD date:
           - Flag as TIMESTAMP_DRIFT (REV-D001)

  D. Check version field (if YAML frontmatter):
     - Extract version from upstream doc
     - Compare to cached version
     - IF version incremented: Flag REV-D003

PHASE 3: Update Cache (MANDATORY)
=========================================
1. Compute SHA-256 hash for ALL upstream documents
2. Create/update .drift_cache.json with:
   - Current hashes
   - Current timestamps
   - Current file sizes
   - Review metadata
3. Append to review_history array

9.3 Hash Calculation (MANDATORY BASH EXECUTION)

CRITICAL: You MUST execute actual bash commands to compute hashes. DO NOT write placeholder values like verified_no_drift or pending_verification.

9.3.1 Compute File Hash

Execute this bash command for each upstream document:

sha256sum <file_path> | cut -d' ' -f1

Example:

sha256sum docs/00_REF/project_governance/engineering_standards.md | cut -d' ' -f1
# Output: a9ca05f4e9b2379465526221271672954feff29e40c57f2a91fe8a050eb46105

Store result in drift cache as: "hash": "sha256:<64_hex_characters>"

9.3.2 Hash Format Validation

Before writing to drift cache, validate the hash:

REJECTED VALUES (re-compute immediately if found):

• sha256:verified_no_drift
• sha256:pending_verification
• pending_verification
• sha256:TBD
• Any value where hex portion != 64 characters

9.3.3 Verification After Cache Write

After updating .drift_cache.json, verify hashes are valid:

# Verify all hashes match valid format
grep -oP '"hash":\s*"sha256:[0-9a-f]{64}"' .drift_cache.json

# Check for any placeholder values (must return empty)
grep -E '"hash":\s*"(sha256:)?(verified_no_drift|pending_verification|TBD)"' .drift_cache.json

If verification fails, re-run sha256sum and update cache before proceeding.

9.3.4 Hash Comparison Algorithm

When comparing hashes for drift detection:

1. Read stored hash from .drift_cache.json
2. Validate stored hash – if placeholder, flag REV-D009 and compute real hash
3. Compute current hash via bash:

   CURRENT_HASH=$(sha256sum <upstream_file> | cut -d' ' -f1)
   

4. Compare:
   • If CURRENT_HASH != stored_hash → Flag REV-D002 (CONTENT_DRIFT)
   • If hashes match → No drift
5. Update cache with current hash and timestamp

9.4 Error Codes

9.5 Report Output

## 9. Upstream Drift Detection (5/5)

### Cache Status

| Field | Value |
|-------|-------|
| Cache File | `.drift_cache.json` |
| Cache Status | ✅ Updated |
| Detection Mode | Hash Comparison |
| Documents Tracked | 2 |

### Upstream Document Analysis

| Upstream Document | Hash Status | Last Modified | Change % | Status |
|-------------------|-------------|---------------|----------|--------|
| F1_IAM_Technical_Specification.md | ✅ Match | 2026-02-10T15:34:26 | 0% | Current |
| GAP_Foundation_Module_Gap_Analysis.md | ✅ Match | 2026-02-10T15:34:21 | 0% | Current |

### Drift Summary

| Status | Count | Details |
|--------|-------|---------|
| ✅ Current | 2 | All upstream documents synchronized |
| ⚠️ Warning | 0 | No drift detected |
| ❌ Critical | 0 | No major changes |

**Cache updated**: 2026-02-10T17:00:00

9.6 Configuration

Review Score Calculation

Canonical Source of Truth:

• ai_dev_ssd_flow/01_BRD/BRD_MVP_VALIDATION_RULES.md (deduction model)
• ai_dev_ssd_flow/01_BRD/README.md (quality-gate interpretation)

Scoring Formula (Deduction-Based):

PRD-Ready Score = 100 - total_deductions

Total: 100 - total_deductions (bounded to 0..100)

Blocking Note: Structure compliance check remains blocking. If structure validation fails (e.g., REV-STR001), the review cannot pass regardless of computed score.

Thresholds:

• PASS: ≥ 90 (configurable)
• FAIL: < 90

Workflow Gate Interpretation:

• >=90: PRD-ready gate satisfied
• <90: not PRD-ready, must route to fix cycle/manual remediation

Command Usage

Basic Usage

# Review specific BRD
/doc-brd-reviewer BRD-01

# Review BRD by path
/doc-brd-reviewer docs/01_BRD/BRD-01_platform/

# Review all BRDs
/doc-brd-reviewer all

Options

Output Report

Review reports are stored alongside the reviewed document per project standards.

Nested Folder Rule: ALL BRDs use nested folders (BRD-NN_{slug}/) regardless of size. This ensures review reports, fix reports, and drift cache files are organized with their parent document.

File Naming: BRD-NN.R_review_report_vNNN.md

Location: Inside the BRD nested folder: docs/01_BRD/BRD-NN_{slug}/

Versioning Rules

1. First Review: Creates BRD-NN.R_review_report_v001.md
2. Subsequent Reviews: Auto-increments version (v002, v003, etc.)
3. Same-Day Reviews: Each review gets unique version number

Version Detection Algorithm:

1. Scan folder for pattern: BRD-NN.R_review_report_v*.md
2. Extract highest version number (N)
3. Create new file with version (N + 1)

Example:

docs/01_BRD/BRD-03_f3_observability/
├── BRD-03.R_review_report_v001.md    # First review
├── BRD-03.R_review_report_v002.md    # After fixes
└── BRD-03.R_review_report_v003.md    # Final review

Delta Reporting

When previous reviews exist, include score comparison:

## Score Comparison

| Metric | Previous (v002) | Current (v003) | Delta |
|--------|-----------------|----------------|-------|
| Overall Score | 85 | 94 | +9 |
| Errors | 3 | 0 | -3 |
| Warnings | 5 | 2 | -3 |

See REVIEW_DOCUMENT_STANDARDS.md for complete requirements.

Integration with doc-brd-autopilot

This skill is invoked during Phase 5 of doc-brd-autopilot:

flowchart LR
    A[Phase 4: Validation] --> B[Phase 5: Final Review]
    B --> C{doc-brd-reviewer}
    C --> D[Phase 6: Continue]

Related Skills

Version History