doc-spec-reviewer

Purpose

Comprehensive content review and quality assurance for Technical Specification (SPEC) documents. This skill performs deep content analysis beyond structural validation, checking YAML structure completeness, REQ coverage, interface definitions, threshold compliance, and identifying issues that require manual review.

Layer: 9 (SPEC Quality Assurance)

Upstream: SPEC (from doc-spec-autopilot or doc-spec )

Downstream: None (final QA gate before TSPEC/TASKS generation)

When to Use This Skill

Use doc-spec-reviewer when:

• After SPEC Generation: Run immediately after doc-spec-autopilot completes

• Manual SPEC Edits: After making manual changes to SPEC

• Pre-TASKS Check: Before running doc-tasks-autopilot

• Pre-TSPEC Check: Before running doc-tspec-autopilot

• Periodic Review: Regular quality checks on existing SPECs

Do NOT use when:

• SPEC does not exist yet (use doc-spec or doc-spec-autopilot first)

• Need structural/schema validation only (use doc-spec-validator )

• Generating new SPEC content (use doc-spec )

Skill vs Validator: Key Differences

Aspect doc-spec-validator

doc-spec-reviewer

Focus Schema compliance, TASKS-Ready score Content quality, implementation readiness

Checks Required sections, YAML syntax REQ coverage, interface completeness

Auto-Fix Structural issues only Content issues (formatting)

Output TASKS-Ready score (numeric) Review score + issue list

Phase Phase 4 (Validation) Phase 5 (Final Review)

Blocking TASKS-Ready < threshold blocks Review score < threshold flags

Review Workflow

flowchart TD A[Input: SPEC Path] --> B[Load SPEC File] B --> C{YAML Valid?}

C -->|Yes| D[Parse YAML Structure]
C -->|No| E[Report Syntax Error]

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

subgraph Review["Review Checks"]
    F --> G[1. YAML Structure Completeness]
    G --> H[2. REQ Coverage]
    H --> I[3. Interface Definition Completeness]
    I --> J[4. Threshold Registry Compliance]
    J --> K[5. Data Model Completeness]
    K --> L[6. Error Handling Coverage]
    L --> M[7. Placeholder Detection]
    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 (MVP) - BLOCKING

Validates SPEC follows the mandatory nested folder rule.

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

Required Structure:

SPEC Type Required Location

YAML docs/09_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml

Error Codes:

Code Severity Description

REV-STR001 Error SPEC not in nested folder (BLOCKING)

REV-STR002 Error Folder name doesn't match SPEC ID

REV-STR003 Warning File name doesn't match folder name

This check is BLOCKING - SPEC must pass structure validation before other checks proceed.

1. YAML Structure Completeness

Validates 13-section YAML structure is complete.

Required Sections:

• metadata

• overview

• traceability

• interfaces

• components

• methods

• data_models

• error_handling

• threshold_registry

• req_implementations

• testing_requirements

• deployment

• appendices

Error Codes:

Code Severity Description

REV-YS001 Error Required YAML section missing

REV-YS002 Error Invalid YAML syntax

REV-YS003 Warning Section is empty

REV-YS004 Info Optional section missing

2. REQ Coverage

Validates all REQ requirements implemented in SPEC.

Scope:

• Every REQ has corresponding implementation

• req_implementations section complete

• Acceptance criteria mapped

• No orphaned specifications

Error Codes:

Code Severity Description

REV-RC001 Error REQ not implemented in SPEC

REV-RC002 Warning Acceptance criteria not mapped

REV-RC003 Warning Orphaned specification (no REQ)

REV-RC004 Info Multiple SPEC items for single REQ (acceptable)

3. Interface Definition Completeness

Validates external, internal, and class interfaces.

Scope:

• External interfaces documented

• Internal interfaces defined

• Class interfaces specified

• Method signatures complete

Error Codes:

Code Severity Description

REV-IF001 Error External interface missing

REV-IF002 Error Method signature incomplete

REV-IF003 Warning Internal interface not defined

REV-IF004 Warning Class interface missing

REV-IF005 Info Parameter types not specified

4. Threshold Registry Compliance

Validates thresholds match upstream documents.

Scope:

• Thresholds from REQ/SYS/PRD/BRD consistent

• Performance targets defined

• SLA requirements met

• Monitoring thresholds set

Error Codes:

Code Severity Description

REV-TR001 Error Threshold mismatch with REQ

REV-TR002 Error Performance target not defined

REV-TR003 Warning SLA requirement may not be met

REV-TR004 Info Monitoring threshold missing

5. Data Model Completeness

Validates data models are implementation-ready.

Scope:

• All types defined

• Field specifications complete

• Validation rules documented

• Relationships mapped

Error Codes:

Code Severity Description

REV-DM001 Error Type not defined

REV-DM002 Warning Field specification incomplete

REV-DM003 Warning Validation rules missing

REV-DM004 Info Relationship not mapped

6. Error Handling Coverage

Validates error scenarios documented.

Scope:

• Error codes defined

• Recovery strategies documented

• Error messages specified

• Retry semantics clear

Error Codes:

Code Severity Description

REV-EH001 Error No error handling defined

REV-EH002 Warning Recovery strategy missing

REV-EH003 Warning Error messages not specified

REV-EH004 Info Retry semantics not documented

7. Placeholder Detection

Identifies incomplete content requiring replacement.

Error Codes:

Code Severity Description

REV-P001 Error [TODO] placeholder found

REV-P002 Error [TBD] placeholder found

REV-P003 Warning Template value not replaced

8. Naming Compliance

Validates element IDs follow doc-naming standards.

Scope:

• Element IDs use SPEC.NN.TT.SS format

• Element type codes valid for SPEC

• Component naming convention

Error Codes:

Code Severity Description

REV-N001 Error Invalid element ID format

REV-N002 Error Element type code not valid for SPEC

REV-N003 Error Legacy pattern detected

9. Upstream Drift Detection (Mandatory Cache)

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

The drift cache is mandatory. All SPEC review operations must maintain drift cache state to enable accurate incremental drift detection. The cache persists hash values between reviews, eliminating false positives from timestamp-only comparisons.

Purpose: Identifies stale SPEC content that may not reflect current REQ and CTR documentation. When REQ documents (requirements, acceptance criteria) or CTR documents (external API contracts) change, the SPEC may need updates to maintain alignment.

Scope:

• @req: tag targets (REQ documents)

• @ctr: tag targets (CTR documents)

• Traceability section upstream artifact links

• Any markdown links to ../07_REQ/ or ../08_CTR/ source documents

Drift Cache File (MANDATORY)

Location: docs/09_SPEC/.drift_cache.json

Schema:

{ "cache_version": "1.0", "last_review": "2026-02-10T17:00:00", "spec_files": { "SPEC-03.yaml": { "spec_hash": "sha256:abc123...", "last_reviewed": "2026-02-10T17:00:00", "upstream_refs": { "REQ-03.yaml": { "file_hash": "sha256:def456...", "section_hashes": { "req_implementations": "sha256:ghi789...", "acceptance_criteria": "sha256:jkl012..." }, "last_modified": "2026-02-08T10:15:00" }, "CTR-03-001.yaml": { "file_hash": "sha256:mno345...", "section_hashes": { "endpoints": "sha256:pqr678..." }, "last_modified": "2026-02-09T14:30:00" } } } } }

Cache Fields:

Field Type Description

cache_version

string Schema version for cache format

last_review

ISO8601 Timestamp of most recent review run

spec_files

object Map of SPEC filename to review state

spec_hash

string SHA-256 hash of SPEC file content

last_reviewed

ISO8601 When this SPEC was last reviewed

upstream_refs

object Map of upstream file to hash state

file_hash

string SHA-256 hash of entire upstream file

section_hashes

object Map of section name to content hash

last_modified

ISO8601 File modification timestamp

Three-Phase Detection Algorithm

Phase 1: Cache Load

1. Load .drift_cache.json from docs/09_SPEC/
2. If cache missing → initialize empty cache, flag REV-D006
3. Validate cache_version compatibility
4. Extract cached state for target SPEC file

Phase 2: Drift Detection

1. Extract all upstream references from SPEC:

   • @req: tags → [path, section anchor]
   • @ctr: tags → [path, section anchor]
   • Links to ../07_REQ/ → [path]
   • Links to ../08_CTR/ → [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 #2) c. Compute current SHA-256 hash of file d. Compare to cached file_hash e. If hash differs → DRIFT detected, proceed to section check f. If section anchor specified:

   • Extract section content
   • Compute SHA-256 of section
   • Compare to cached section_hash
   • If differs → SECTION_DRIFT detected

Phase 3: Cache Update

1. After review completes (regardless of pass/fail): a. Update spec_hash with current SPEC hash b. Update last_reviewed timestamp c. For each upstream reference:
   • Update file_hash
   • Update section_hashes
   • Update last_modified d. Write .drift_cache.json atomically
2. Cache update is MANDATORY - failure to update is REV-D006

Hash Calculation (MANDATORY BASH EXECUTION)

CRITICAL: Execute actual bash commands. DO NOT write placeholder values.

Full File Hash:

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

Store as: "hash": "sha256:<64_hex_characters>"

Section Hash (for YAML sections):

Extract YAML section and hash

yq '.<section_name>' <file_path> | sha256sum | cut -d' ' -f1

REJECTED VALUES (re-compute immediately):

• sha256:verified_no_drift

• sha256:pending_verification

• Any value where hex portion != 64 characters

Verification:

grep -oP '"hash":\s*"sha256:[0-9a-f]{64}"' .drift_cache.json

Error Codes

Code Severity Description

REV-D001 Warning Upstream REQ/CTR document modified after SPEC creation

REV-D002 Warning Referenced section content has changed (hash mismatch)

REV-D003 Info Upstream document version incremented

REV-D004 Info New content added to upstream document

REV-D005 Error Critical upstream document substantially modified (>20% change)

REV-D006 Error Drift cache missing or invalid - cache is mandatory

REV-D009 Error Invalid hash placeholder detected (verified_no_drift , pending_verification )

Report Output

Upstream Drift Analysis

Cache Status: Active (last updated: 2026-02-10T14:30:00)

Drift Summary:

• Files checked: 2
• Files with drift: 1
• Sections with drift: 1

Recommendation: Review upstream REQ/CTR changes and update SPEC if requirements or contracts have changed.

Auto-Actions

• Mandatory: Update .drift_cache.json with current hashes after every review

• Add [DRIFT] marker to affected @req/@ctr tags (optional)

• Generate drift summary in review report

Configuration

Setting Default Description

cache_enabled

true Mandatory - cache cannot be disabled

drift_threshold_days

7 Days before drift becomes Warning

critical_threshold_days

30 Days before drift becomes Error

tracked_patterns

@req: , @ctr:

Patterns to track for drift

Review Score Calculation

Scoring Formula:

Category Weight Calculation

YAML Structure Completeness 14% (complete_sections / 13) × 14

REQ Coverage 19% (implemented / total_reqs) × 19

Interface Definition Completeness 19% (complete_interfaces / total) × 19

Threshold Registry Compliance 10% (compliant / total_thresholds) × 10

Data Model Completeness 14% (complete_models / total) × 14

Error Handling Coverage 5% (covered / required) × 5

Placeholder Detection 5% (no_placeholders ? 5 : 5 - count)

Naming Compliance 9% (valid_ids / total_ids) × 9

Upstream Drift 5% (fresh_refs / total_refs) × 5

Total: Sum of all categories (max 100)

Thresholds:

• PASS: >= 90

• WARNING: 80-89

• FAIL: < 80

Command Usage

Review specific SPEC

/doc-spec-reviewer SPEC-03

Review SPEC by path

/doc-spec-reviewer docs/09_SPEC/SPEC-03.yaml

Review all SPECs

/doc-spec-reviewer all

Output Report

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

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

File Naming: SPEC-NN.R_review_report_vNNN.md

Audit Wrapper Compatibility: doc-spec-audit may emit preferred SPEC-NN.A_audit_report_vNNN.md ; reviewer output remains valid legacy-compatible input for fixer.

Location: Inside the SPEC nested folder: docs/09_SPEC/SPEC-NN_{slug}/

Versioning Rules

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

Example:

docs/09_SPEC/SPEC-03_f3_observability/ ├── SPEC-03_f3_observability.yaml ├── SPEC-03.R_review_report_v001.md # First review ├── SPEC-03.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-spec-autopilot

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

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

Related Skills

Skill Relationship

doc-naming

Naming standards for Check #8

doc-spec-autopilot

Invokes this skill in Phase 5

doc-spec-validator

Structural validation (Phase 4)

doc-spec-fixer

Applies fixes based on review findings

doc-spec

SPEC creation rules

doc-req-reviewer

Upstream QA

doc-ctr-reviewer

Upstream QA (for external APIs)

doc-tasks-autopilot

Downstream consumer

doc-tspec-autopilot

Downstream consumer

Version History

Version Date Changes

1.5 2026-02-27 Normalized metadata schema; aligned structure heading to MVP contract; added audit-wrapper compatibility for .A_ reports

1.4 2026-02-11 Structure Compliance BLOCKING check: Added Check #0 as BLOCKING prerequisite; Validates nested folder rule for SPEC documents; REV-STR001-STR003 error codes; Must pass before other checks proceed

1.3 2026-02-10 Mandatory drift cache: Cache is now required (REV-D006 error if missing); Three-phase detection algorithm; SHA-256 hash calculation with Python implementation; Enhanced cache schema with section-level hashing; Cache status in report output

1.2 2026-02-10 Added Check #9: Upstream Drift Detection - detects when REQ/CTR documents modified after SPEC creation; REV-D001-D005 error codes; drift cache support; configurable thresholds; added doc-spec-fixer to related skills

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; YAML structure validation; REQ coverage; Interface completeness; Threshold compliance

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.

• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt .

• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.

• Do not introduce legacy fallback paths such as docs-v2.0/00_REF .