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

Aspect	`doc-brd-validator`	`doc-brd-reviewer`
Focus	Schema compliance, PRD-Ready score	Content quality, strategic alignment
Checks	Required sections, field formats	Link integrity, ADR completeness, placeholders
Auto-Fix	Structural issues only	Content issues (links, dates, placeholders)
Output	PRD-Ready score (numeric)	Review score + issue list
Phase	Phase 4 (Validation)	Phase 5 (Final Review)
Blocking	PRD-Ready < threshold blocks	Review score < threshold flags

Review Workflow

mermaid

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

BRD Type	Required Location
Monolithic	`docs/01_BRD/BRD-NN_{slug}/BRD-NN_{slug}.md`
Sectioned	`docs/01_BRD/BRD-NN_{slug}/BRD-NN.0_index.md` , `BRD-NN.1_*.md` , etc.

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:

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

Error Codes:

Code	Severity	Description
REV-STR001	Error	BRD not in nested folder (blocking)
REV-STR002	Error	BRD folder name doesn't match BRD ID
REV-STR003	Warning	Monolithic BRD should be sectioned (>25KB)

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 (
```
[See Section 7.2](...)
```
)
Index to section links
External documentation links (warns if unreachable)

Error Codes:

Code	Severity	Description
REV-L001	Error	Broken internal link
REV-L002	Warning	External link unreachable
REV-L003	Info	Link path uses absolute instead of relative

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:

Code	Severity	Description
REV-R001	Error	Requirement missing acceptance criteria
REV-R002	Error	No success metrics defined
REV-R003	Warning	Scope boundaries unclear
REV-R004	Warning	Missing priority assignment
REV-R005	Info	Dependency not documented

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:

Code	Severity	Description
REV-ADR001	Error	Mandatory ADR category missing
REV-ADR002	Error	Topic missing Alternatives Overview
REV-ADR003	Error	Selected topic missing comparison table
REV-ADR004	Warning	Topic missing Decision Drivers
REV-ADR005	Info	Deferred topic needs justification

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

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

Code	Severity	Description
REV-P001	Error	[TODO] placeholder found
REV-P002	Error	[TBD] placeholder found
REV-P003	Warning	Template date not replaced
REV-P004	Warning	Template name not replaced
REV-P005	Warning	Empty section content

5. Traceability Tags

Validates

@strategy:

and cross-reference tags.

Scope:

```
@strategy: DOC-XX
```
tags reference valid source documents
Element IDs properly formatted
Cross-references consistent

Error Codes:

Code	Severity	Description
REV-TR001	Error	Invalid strategy reference
REV-TR002	Warning	Missing element ID
REV-TR003	Info	Inconsistent cross-reference format
REV-TR004	Warning	Tag format malformed

6. Section Completeness

Verifies all required sections have substantive content.

Scope:

Minimum word count per section (configurable)
Section headers present
Tables have data rows (not just headers)
Mermaid diagrams render properly

Minimum Word Counts (configurable):

Section	Minimum Words
Executive Summary	100
Problem Statement	75
Business Objectives	150
Functional Requirements	200
Non-Functional Requirements	150
ADR Topics	300
Appendices	100

Error Codes:

Code	Severity	Description
REV-S001	Error	Required section missing entirely
REV-S002	Warning	Section below minimum word count
REV-S003	Warning	Table has no data rows
REV-S004	Error	Mermaid diagram syntax error

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

Error Codes:

Code	Severity	Description
REV-SA001	Warning	Business objective not traced to strategy
REV-SA002	Info	Success metric may not align with KPI
REV-SA003	Warning	Scope may exceed project charter
REV-SA004	Flag	Requires stakeholder review

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:

Code	Severity	Description
REV-N001	Error	Invalid element ID format
REV-N002	Error	Element type code not valid for BRD
REV-N003	Error	Legacy pattern detected
REV-N004	Warning	Inconsistent ID sequencing

9. Upstream Drift Detection (Mandatory Cache)

Detects when upstream source documents have been modified after the BRD was created or last updated. The drift cache is mandatory - the reviewer MUST create/update it after each review.

Purpose: Identifies stale BRD content that may not reflect current source documentation. When upstream documents (strategy specs, technical specifications, stakeholder inputs) change, the BRD may need updates to maintain alignment.

Scope:

```
@ref:
```
tag targets (technical specifications, strategy documents)
```
@strategy:
```
tag references
Traceability section upstream artifact links
GAP analysis document references
Any markdown links to
```
../00_REF/
```
or source documents

9.1 Drift Cache File (MANDATORY)

Location:

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

IMPORTANT: The reviewer MUST:

Read the cache if it exists (for hash comparison)
Create the cache if it doesn't exist
Update the cache after every review with current hashes

Cache Schema:

json

{
  "schema_version": "1.0",
  "document_id": "BRD-01",
  "document_version": "1.0",
  "last_reviewed": "2026-02-10T17:00:00",
  "reviewer_version": "1.4",
  "upstream_documents": {
    "../../00_REF/foundation/F1_IAM_Technical_Specification.md": {
      "hash": "sha256:a1b2c3d4e5f6g7h8i9j0...",
      "last_modified": "2026-02-10T15:34:26",
      "file_size": 50781,
      "version": "1.0",
      "sections_tracked": ["#3-authentication", "#4-authorization", "#5-user-profile"]
    },
    "../../00_REF/foundation/GAP_Foundation_Module_Gap_Analysis.md": {
      "hash": "sha256:k1l2m3n4o5p6q7r8s9t0...",
      "last_modified": "2026-02-10T15:34:21",
      "file_size": 4730,
      "version": "1.0",
      "sections_tracked": ["#f1-iam-gaps"]
    }
  },
  "review_history": [
    {
      "date": "2026-02-10T16:30:00",
      "score": 97,
      "drift_detected": false,
      "report_version": "v002"
    }
  ]
}

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

python

import hashlib
from pathlib import Path

def compute_file_hash(file_path: str) -> str:
    """Compute SHA-256 hash of file content."""
    sha256 = hashlib.sha256()
    with open(file_path, 'rb') as f:
        for chunk in iter(lambda: f.read(8192), b''):
            sha256.update(chunk)
    return f"sha256:{sha256.hexdigest()}"

def compute_section_hash(file_path: str, section_anchor: str) -> str:
    """Compute hash of specific section (for anchor references)."""
    content = Path(file_path).read_text()
    # Extract section from anchor to next heading
    section_pattern = f"#{section_anchor.lstrip('#')}"
    # ... section extraction logic ...
    section_content = extract_section(content, section_pattern)
    return f"sha256:{hashlib.sha256(section_content.encode()).hexdigest()}"

def calculate_change_percentage(old_hash: str, new_content: str) -> float:
    """Estimate change percentage using content diff."""
    # Use difflib to calculate similarity ratio
    import difflib
    # ... comparison logic ...
    return change_percentage

9.4 Error Codes

Code	Severity	Description	Trigger
REV-D001	Warning	Upstream document modified after BRD creation	mtime > BRD date (no cache)
REV-D002	Warning	Referenced content has changed	hash mismatch (with cache)
REV-D003	Info	Upstream document version incremented	version field changed
REV-D004	Info	New content added to upstream	file size increased >10%
REV-D005	Error	Critical modification (>20% change)	hash diff >20%
REV-D006	Info	Cache created (first review)	no prior cache existed

9.5 Report Output

markdown

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

Setting	Default	Description
`cache_enabled`	true	Mandatory - always create/update cache
`drift_threshold_days`	7	Days before timestamp drift becomes Warning
`critical_change_pct`	20	Percentage change for critical drift
`track_sections`	true	Track individual section hashes for anchored refs
`max_history_entries`	10	Maximum review_history entries to retain

Review Score Calculation

Scoring Formula:

Category	Weight	Calculation
Structure Compliance	12%	(nested_folder_valid ? 12 : 0) - BLOCKING
Link Integrity	8%	(valid_links / total_links) × 8
Requirement Completeness	15%	(complete_reqs / total_reqs) × 15
ADR Topic Coverage	15%	(covered_topics / required_topics) × 15
Placeholder Detection	10%	(no_placeholders ? 10 : 10 - (count × 2))
Traceability Tags	10%	(valid_tags / total_tags) × 10
Section Completeness	12%	(complete_sections / total_sections) × 12
Strategic Alignment	5%	(aligned_objectives / total_objectives) × 5
Naming Compliance	8%	(valid_ids / total_ids) × 8
Upstream Drift	5%	(fresh_refs / total_refs) × 5

Total: Sum of all categories (max 100)

Note: Structure Compliance is a blocking check. If structure validation fails (REV-STR001), the review cannot pass regardless of other scores.

Thresholds:

PASS: ≥ 90 (configurable)
WARNING: 80-89
FAIL: < 80

Command Usage

Basic Usage

bash

# 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

Option	Default	Description
`--min-score`	90	Minimum passing review score
`--auto-fix`	true	Apply automatic fixes
`--no-auto-fix`	false	Disable auto-fix (report only)
`--check`	all	Specific checks to run (comma-separated)
`--skip`	none	Checks to skip (comma-separated)
`--verbose`	false	Detailed output per check
`--report`	true	Generate markdown report

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

First Review: Creates
```
BRD-NN.R_review_report_v001.md
```
Subsequent Reviews: Auto-increments version (v002, v003, etc.)
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:

markdown

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

mermaid

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

Related Skills

Skill	Relationship
`doc-naming`	Naming standards for Check #8
`doc-brd-autopilot`	Invokes this skill in Phase 5
`doc-brd-validator`	Structural validation (Phase 4)
`doc-brd-fixer`	Applies fixes based on review findings
`doc-brd`	BRD creation rules
`doc-prd-autopilot`	Downstream consumer

Version History

Version	Date	Changes
1.5	2026-02-11T18:00:00	Structure Compliance: Added Check #0 for nested folder rule enforcement (REV-STR001-STR003); Updated workflow diagram with structure validation decision node; Added structure compliance to scoring (12% weight, blocking); Consistent with other reviewer skills
1.4	2026-02-10T17:00:00	Mandatory drift cache: Reviewer MUST create/update `.drift_cache.json` after every review; Three-phase detection algorithm; SHA-256 hash computation; Hash comparison mode when cache exists; REV-D006 code for cache creation; Cache schema with review_history tracking
1.3	2026-02-10T14:30:00	Added Check #9: Upstream Drift Detection - detects when source documents modified after BRD creation; REV-D001-D005 error codes; drift cache support; configurable thresholds
1.2	2026-02-10	Added element type code 33 (Benefit Statement) to valid BRD codes per doc-naming v1.5
1.1	2026-02-10	Added review versioning support (_vNNN pattern); Delta reporting for score comparison
1.0	2026-02-10	Initial skill creation with 8 review checks; ADR topic coverage validation; Strategic alignment check

doc-brd-reviewer

NPX Install

Tags

SKILL.md Content

doc-brd-reviewer

Purpose

When to Use This Skill

Skill vs Validator: Key Differences

Review Workflow

Review Checks

0. Structure Compliance (BLOCKING)

1. Link Integrity

2. Requirement Completeness

3. ADR Topic Coverage

4. Placeholder Detection

5. Traceability Tags

6. Section Completeness

7. Strategic Alignment

8. Naming Compliance

9. Upstream Drift Detection (Mandatory Cache)

9.1 Drift Cache File (MANDATORY)

9.2 Detection Algorithm (Three-Phase)

9.3 Hash Calculation

9.4 Error Codes

9.5 Report Output

9.6 Configuration

Review Score Calculation

Command Usage

Basic Usage

Options

Output Report

Versioning Rules

Delta Reporting

Integration with doc-brd-autopilot

Related Skills

Version History