doc-req-reviewer

Purpose

Comprehensive content review and quality assurance for Atomic Requirements (REQ) documents. This skill performs deep content analysis beyond structural validation, checking requirement atomicity, SYS alignment, implementation paths, unit test coverage, and identifying issues that require manual review.

Layer: 7 (REQ Quality Assurance)

Upstream: REQ (from doc-req-autopilot or doc-req)

Downstream: None (final QA gate before SPEC/CTR generation)

When to Use This Skill

Use doc-req-reviewer when:

• After REQ Generation: Run immediately after doc-req-autopilot completes
• Manual REQ Edits: After making manual changes to REQ
• Pre-SPEC Check: Before running doc-spec-autopilot
• Pre-CTR Check: Before running doc-ctr-autopilot
• Periodic Review: Regular quality checks on existing REQs

Do NOT use when:

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

Skill vs Validator: Key Differences

Review Workflow

flowchart TD
    A[Input: REQ Path] --> B[Load REQ Files]
    B --> C{Single or Module?}

    C -->|Module| D[Load All REQ Files]
    C -->|Single| E[Load Single File]

    D --> F[Run Review Checks]
    E --> F

    subgraph Review["Review Checks"]
        F --> G[1. Requirement Atomicity]
        G --> H[2. SYS Alignment]
        H --> I[3. Acceptance Criteria Quality]
        I --> J[4. Implementation Path Completeness]
        J --> K[5. Unit Test Category Coverage]
        K --> L[6. Cross-Link Integrity]
        L --> M[7. Placeholder Detection]
        M --> M2[8. Naming Compliance]
        M2 --> N2[9. Upstream Drift Detection]
    end

    N2 --> 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 (12/12) – BLOCKING

Validates REQ follows the mandatory nested folder rule.

Nested Folder Rule: ALL REQ documents MUST be in nested folders.

Required Structure:

Error Codes:

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

1. Requirement Atomicity

Validates each requirement is truly atomic.

Scope:

• Single responsibility
• No compound requirements
• Independently testable
• Clear scope boundaries

Error Codes:

2. SYS Alignment

Validates REQ traces to SYS requirements.

Scope:

• Every REQ maps to SYS requirement
• Decomposition is complete
• No orphaned requirements
• Functional coverage maintained

Error Codes:

3. Acceptance Criteria Quality

Validates acceptance criteria are comprehensive.

Scope:

• Minimum 10 functional criteria
• Minimum 5 quality criteria
• Categories covered ([Logic], [Validation], [State], [Edge], [Security])
• Measurable outcomes

Error Codes:

4. Implementation Path Completeness

Validates Section 11 implementation guidance.

Scope:

• Code implementation paths defined
• Module locations specified
• Dependencies documented
• Method signatures suggested

Error Codes:

5. Unit Test Category Coverage

Validates Section 8 test categories.

Scope:

• All 5 categories present ([Logic], [Validation], [State], [Edge], [Security])
• Minimum test cases per category
• Test rationale documented

Error Codes:

6. Cross-Link Integrity

Validates Section 10.5 cross-links.

Scope:

• @discoverability tags valid
• Related REQs exist
• Bidirectional links present

Error Codes:

7. Placeholder Detection

Identifies incomplete content requiring replacement.

Error Codes:

8. Naming Compliance

Validates element IDs follow doc-naming standards.

Scope:

• Element IDs use REQ.NN.TT.SS format
• Element type codes valid for REQ (01, 05, 06, 27)
• Atomic file naming convention

Error Codes:

9. Upstream Drift Detection (Mandatory Cache)

Detects when upstream SYS documents have been modified after the REQ was created or last updated.

The drift cache is mandatory – the reviewer MUST create/update it after every review.

Purpose: Identifies stale REQ content that may not reflect current system requirements. When SYS documents change, the REQ may need updates to maintain alignment with system-level specifications.

Upstream Documents:

• SYS documents: System Requirements that REQ atomic requirements decompose from

Scope:

• @sys: tag targets (SYS document references)
• Traceability section upstream artifact links
• Any markdown links to ../06_SYS/
• Section 10 parent requirement references

Detection Methods:

Drift Cache File (MANDATORY):

Location: docs/07_REQ/.drift_cache.json

{
  "cache_version": "1.0",
  "last_review": "2026-02-10T17:00:00",
  "reviewer_version": "1.3",
  "upstream_hashes": {
    "docs/06_SYS/SYS-01_f1_iam.md": {
      "hash": "a1b2c3d4e5f6...",
      "mtime": "2026-02-08T10:15:00",
      "version": "1.0"
    },
    "docs/06_SYS/SYS-03_f3_observability.md": {
      "hash": "e5f6g7h8i9j0...",
      "mtime": "2026-02-10T14:30:00",
      "version": "1.2"
    }
  },
  "req_states": {
    "REQ-01": {
      "last_reviewed": "2026-02-10T17:00:00",
      "upstream_refs": ["docs/06_SYS/SYS-01_f1_iam.md"]
    },
    "REQ-03": {
      "last_reviewed": "2026-02-10T17:00:00",
      "upstream_refs": ["docs/06_SYS/SYS-03_f3_observability.md"]
    }
  }
}

Three-Phase Detection Algorithm:

Phase 1: Load Cache
─────────────────────
1. Check if docs/07_REQ/.drift_cache.json exists
2. If exists:
   a. Load cached upstream hashes
   b. Load cached REQ states
3. If not exists:
   a. Initialize empty cache structure
   b. Flag as first review (REV-D006)

Phase 2: Detect Drift
─────────────────────
1. Extract all upstream references from REQ:
   - @sys: tags → [SYS document ID, requirement ID]
   - Links to ../06_SYS/ → [path]
   - Traceability table upstream artifacts → [path]
   - Section 10 parent SYS requirement → [SYS.NN.TT.SS]

2. For each upstream reference:
   a. Resolve path to absolute file path
   b. Check file exists (already covered by Check #2)
   c. Compute current SHA-256 hash
   d. Compare to cached hash
   e. If hash differs → flag as DRIFT (REV-D002)
   f. If mtime > REQ last_reviewed → flag as TIMESTAMP_DRIFT (REV-D001)

3. Calculate drift severity:
   a. Compute content diff percentage
   b. If >20% change → Critical (REV-D005)
   c. If version incremented → Info (REV-D003)

Phase 3: Update Cache (MANDATORY)
─────────────────────────────────
1. For each upstream document reviewed:
   a. Compute current SHA-256 hash
   b. Record current mtime
   c. Extract version from frontmatter
2. Update req_states with review timestamp
3. Write updated cache to docs/07_REQ/.drift_cache.json
4. Cache update is MANDATORY - never skip this step

Hash Calculation:

import hashlib

def compute_upstream_hash(file_path: str) -> str:
    """Compute SHA-256 hash of upstream document content."""
    with open(file_path, 'r', encoding='utf-8') as f:
        content = f.read()
    return hashlib.sha256(content.encode('utf-8')).hexdigest()

Error Codes:

Report Output:

## Upstream Drift Analysis

**Cache Status**: Updated | Created | N/A
**Cache Location**: docs/07_REQ/.drift_cache.json

| Upstream Document | REQ Reference | Last Modified | REQ Updated | Days Stale | Severity |
|-------------------|---------------|---------------|-------------|------------|----------|
| SYS-01_f1_iam.md | @sys Section 3.2 | 2026-02-08T10:15:00 | 2026-02-05T09:00:00 | 3 | Warning |
| SYS-03_f3_observability.md | Traceability | 2026-02-10T14:30:00 | 2026-02-05T09:00:00 | 5 | Warning |

**Recommendation**: Review upstream SYS changes and update REQ if system requirements have changed.

Auto-Actions:

• Update docs/07_REQ/.drift_cache.json with current hashes after review (MANDATORY)
• Add [DRIFT] marker to affected @sys tags (optional)
• Generate drift summary in review report

Configuration:

Review Score Calculation

Scoring Formula:

Total: Sum of all categories (max 100)

Thresholds:

• PASS: ≥ 90
• WARNING: 80-89
• FAIL: < 80

Command Usage

# Review specific REQ module
/doc-req-reviewer REQ-03

# Review specific atomic REQ
/doc-req-reviewer REQ-03-001

# Review REQ by path
/doc-req-reviewer docs/07_REQ/REQ-03_f3_observability/

# Review all REQs
/doc-req-reviewer all

Output Report

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

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

File Naming: REQ-NN.R_review_report_vNNN.md (module-level) or REQ-NN-SSS.R_review_report_vNNN.md (atomic-level)

Location: Inside the REQ nested folder: docs/REQ/REQ-NN_{slug}/

Versioning Rules

1. First Review: Creates REQ-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: Scans folder for existing REQ-NN.R_review_report_v*.md files and increments.

Example:

docs/REQ/REQ-03_f3_observability/
├── REQ-03-001_metrics_collection.md
├── REQ-03-001.R_review_report_v001.md    # First review
├── REQ-03-001.R_review_report_v002.md    # After fixes
└── .drift_cache.json

Delta Reporting

When previous reviews exist, include score comparison in the report.

See REVIEW_DOCUMENT_STANDARDS.md for complete versioning requirements.

Integration with doc-req-autopilot

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

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

Related Skills

Version History