doc-adr-reviewer

Purpose

Comprehensive content review and quality assurance for Architecture Decision Records (ADR). This skill performs deep content analysis beyond structural validation, checking decision completeness, BRD topic alignment, consequence coverage, alternative evaluation, and identifying issues that require manual architectural review.

Layer: 5 (ADR Quality Assurance)

Upstream: ADR (from doc-adr-autopilot or doc-adr)

Downstream: None (final QA gate before SYS generation)

When to Use This Skill

Use doc-adr-reviewer when:

• After ADR Generation: Run immediately after doc-adr-autopilot completes
• Manual ADR Edits: After making manual changes to ADR
• Pre-SYS Check: Before running doc-sys-autopilot
• Periodic Review: Regular quality checks on existing ADRs
• Architecture Reviews: During formal architecture review sessions

Do NOT use when:

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

Skill vs Validator: Key Differences

Review Workflow

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

    C -->|Multiple| D[Load All ADR Files]
    C -->|Single| E[Load Single File]

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

    subgraph Review["Review Checks"]
        F --> G[1. Decision Completeness]
        G --> H[2. BRD Topic Alignment]
        H --> I[3. Consequence Coverage]
        I --> J[4. Alternative Evaluation]
        J --> K[5. Cross-Reference Integrity]
        K --> L[6. Placeholder Detection]
        L --> M[7. Naming Compliance]
        M --> N2[8. 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 ADR follows the mandatory nested folder rule.

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

Required Structure:

Error Codes:

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

1. Decision Completeness

Validates ADR has all required decision components.

Scope:

• Context clearly stated
• Decision explicitly documented
• Rationale provided
• Status defined
• Date recorded

Error Codes:

2. BRD Topic Alignment

Validates ADR addresses BRD Section 7.2 topics.

Scope:

• ADR maps to BRD ADR topic
• Topic category correct (Infrastructure, Data, Security, etc.)
• Decision matches topic requirements
• All BRD topics have corresponding ADRs

Error Codes:

3. Consequence Coverage

Validates positive and negative consequences documented.

Scope:

• Positive consequences listed
• Negative consequences/trade-offs acknowledged
• Risk assessment included
• Mitigation strategies defined

Error Codes:

4. Alternative Evaluation

Validates alternatives were properly considered.

Scope:

• Multiple alternatives evaluated
• Comparison criteria defined
• Trade-off analysis present
• Rejection reasons documented

Error Codes:

5. Cross-Reference Integrity

Validates links to related ADRs and documents.

Scope:

• Related ADRs referenced
• Superseded ADRs linked
• BRD/PRD traceability tags present
• External references valid

Error Codes:

6. Placeholder Detection

Identifies incomplete content requiring replacement.

Error Codes:

7. Naming Compliance

Validates element IDs follow doc-naming standards.

Scope:

• Element IDs use ADR.NN.TT.SS format
• Element type codes valid for ADR (13, 14, 15, 16)
• ADR numbering sequential

Error Codes:

8. Upstream Drift Detection (Mandatory Cache)

Detects when upstream source documents have been modified after the ADR was created or last updated.

The drift cache is mandatory. All drift detection operations must read from and write to the cache file. Reviewers must fail with REV-D006 if the cache file cannot be created or accessed.

Purpose: Identifies stale ADR content that may not reflect current BDD scenarios. When upstream documents change, the ADR may need updates to maintain alignment.

Upstream Documents:

• BDD documents: Feature files and scenario definitions that ADR decisions must support

Scope:

• @bdd: tag targets (BDD feature files)
• Traceability section upstream artifact links
• Any markdown links to ../04_BDD/

Drift Cache File (MANDATORY)

Location: docs/05_ADR/.drift_cache.json

Schema:

{
  "cache_version": "1.0",
  "last_updated": "2026-02-10T17:00:00",
  "documents": {
    "ADR-01_authentication_strategy.md": {
      "adr_hash": "sha256:abc123...",
      "adr_updated": "2026-02-10T17:00:00",
      "upstream_refs": {
        "../../04_BDD/BDD-01_authentication.feature": {
          "hash": "sha256:def456...",
          "last_checked": "2026-02-10T17:00:00",
          "status": "current"
        }
      }
    }
  }
}

Cache Requirements:

1. Cache file MUST be created on first review if it does not exist
2. Cache MUST be updated after every review run
3. Cache entries MUST include SHA-256 hashes for all upstream references
4. Stale cache entries (>30 days) MUST trigger re-validation

Three-Phase Detection Algorithm

PHASE 1: Cache Initialization
   1. Check if .drift_cache.json exists
   2. If not exists → create with empty documents object
   3. If exists → load and validate schema
   4. If schema invalid → backup and recreate

PHASE 2: Upstream Reference Extraction
   1. Extract all upstream references from ADR:
      - @bdd: tags → [path, scenario anchor]
      - Links to ../04_BDD/ → [path]
      - Traceability table upstream artifacts → [path]

   2. For each upstream reference:
      a. Resolve path to absolute file path
      b. Check file exists (already covered by Check #5)
      c. Read file content
      d. Compute SHA-256 hash of content

PHASE 3: Drift Comparison
   1. For each upstream reference:
      a. Look up cached hash for this reference
      b. If no cached hash → flag as NEW_REFERENCE
      c. If hash matches → status = "current"
      d. If hash differs → flag as CONTENT_DRIFT

   2. Calculate drift severity:
      a. Compare content size change percentage
      b. If >20% change → CRITICAL (REV-D005)
      c. If <20% change → WARNING (REV-D002)

   3. Update cache with new hashes and timestamps

Hash Calculation

Algorithm: SHA-256

Python Implementation:

import hashlib

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

Hash Scope:

• Full file content for BDD feature files
• Specific section content when anchor specified (e.g., #scenario-login)

Error Codes

Report Output

## Upstream Drift Analysis

**Cache Status**: Active | Last Updated: 2026-02-10T17:00:00

| Upstream Document | ADR Reference | Current Hash | Cached Hash | Status | Severity |
|-------------------|---------------|--------------|-------------|--------|----------|
| BDD-01_authentication.feature | @bdd Section 3 | sha256:abc... | sha256:def... | DRIFT | Warning |
| BDD-02_authorization.feature | @bdd Section 5 | sha256:ghi... | sha256:ghi... | Current | - |

**Drift Summary**:
- Documents checked: 2
- Current: 1
- Drifted: 1
- Critical: 0

**Recommendation**: Review upstream changes and update ADR if decision context has changed.

Auto-Actions

1. Cache Update: Update .drift_cache.json with current hashes after every review
2. Drift Markers: Add [DRIFT] marker to affected @bdd tags (optional)
3. Report Generation: Include drift summary in review report
4. Cache Backup: Create .drift_cache.json.bak before updates

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 ADR
/doc-adr-reviewer ADR-01

# Review ADR by path
/doc-adr-reviewer docs/05_ADR/ADR-01_authentication_strategy.md

# Review all ADRs
/doc-adr-reviewer all

Output Report

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

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

File Naming: ADR-NN.R_review_report_vNNN.md

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

Versioning Rules

1. First Review: Creates ADR-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 ADR-NN.R_review_report_v*.md files and increments.

Example:

docs/ADR/ADR-01_authentication_strategy/
├── ADR-01_authentication_strategy.md
├── ADR-01.R_review_report_v001.md    # First review
├── ADR-01.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-adr-autopilot

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

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

Related Skills

Version History