home / skills / vladm3105 / aidoc-flow-framework / doc-brd-reviewer
/ai_dev_ssd_flow/01_BRD/.backup_2026-02-25/doc-brd-reviewer
This skill performs deep BRD content quality review, validating link integrity, ADR coverage, and strategic alignment to flag issues needing manual review.
npx playbooks add skill vladm3105/aidoc-flow-framework --skill doc-brd-reviewerReview the files below or copy the command above to add this skill to your agents.
---
name: doc-brd-reviewer
description: Comprehensive content review and quality assurance for BRD documents - validates link integrity, requirement completeness, strategic alignment, and identifies issues requiring manual attention
tags:
- sdd-workflow
- quality-assurance
- brd-review
- layer-1-artifact
- shared-architecture
custom_fields:
layer: 1
artifact_type: BRD
architecture_approaches: [ai-agent-based]
priority: primary
development_status: active
skill_category: quality-assurance
upstream_artifacts: [Strategy, Stakeholder Input]
downstream_artifacts: []
version: "1.6"
last_updated: "2026-02-24T21:30:00"
---
# 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**:
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**:
| 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: `<!-- 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**:
| 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 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**:
| Code | Severity | Description |
|------|----------|-------------|
| REV-TR001 | Error | Invalid document ID in metadata |
| REV-TR002 | Warning | Missing element ID |
| REV-TR003 | Info | Inconsistent cross-reference format |
| REV-TR004 | Warning | Malformed parent_doc reference |
---
### 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 (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:
| upstream_mode | Action | Score |
|---------------|--------|-------|
| `"none"` (default) | Skip Check #9 entirely | 5/5 automatic |
| `"ref"` | Run drift detection on `upstream_ref_path` | Calculated |
| *(not set)* | Treat as `"none"` | 5/5 automatic |
**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):
```json
{
"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"`):
```json
{
"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",
"score": 97,
"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
```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 |
| REV-D007 | Info | Drift detection skipped | upstream_mode: "none" |
| REV-D008 | Warning | upstream_ref_path not found | specified path doesn't exist |
---
#### 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% | `upstream_mode == "none"` ? 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
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:
```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.6 | 2026-02-24T21:30:00 | **Conditional drift detection**: Check #9 now skipped when `upstream_mode: "none"` (default); Removed @strategy: tag references; Updated drift cache schema to v1.1 with upstream_mode and drift_detection_skipped fields; Added REV-D007 (drift skipped) and REV-D008 (path not found) error codes; Updated scoring formula for conditional check |
| 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 |
This skill performs comprehensive content review and quality assurance for Business Requirements Documents (BRD). It validates structure and link integrity, checks requirement completeness and ADR coverage, detects placeholders and upstream drift, and produces a review score plus actionable issue list. The reviewer can auto-fix some problems but flags content that requires manual business review.
The reviewer loads a BRD (sectioned or monolithic), runs a blocking structure compliance check, then executes targeted checks: link integrity, requirement completeness, ADR topic coverage, placeholder detection, traceability tags, section completeness, strategic alignment, naming compliance, and upstream drift detection. It categorizes issues, applies auto-fixes where safe, updates a mandatory .drift_cache.json with upstream hashes, and calculates a review score with pass/fail gating.
Does the reviewer auto-fix all issues?
No. It auto-fixes structural and low-risk template issues (folder moves, dates, some naming) but flags content gaps, business decisions, and TODOs for manual resolution.
What is the drift cache and why is it mandatory?
The drift cache (.drift_cache.json) stores upstream file hashes, timestamps, and review history so subsequent reviews can reliably detect content drift. Updating it after every review is required to maintain accurate drift detection.