doc-spec-reviewer（文档规范审阅者）

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

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:

Error Codes:

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:

1. metadata
2. overview
3. traceability
4. interfaces
5. components
6. methods
7. data_models
8. error_handling
9. threshold_registry
10. req_implementations
11. testing_requirements
12. deployment
13. appendices

Error Codes:

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:

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:

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:

5. Data Model Completeness

Validates data models are implementation-ready.

Scope:

• All types defined
• Field specifications complete
• Validation rules documented
• Relationships mapped

Error Codes:

6. Error Handling Coverage

Validates error scenarios documented.

Scope:

• Error codes defined
• Recovery strategies documented
• Error messages specified
• Retry semantics clear

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 SPEC.NN.xxxx format
• Element type codes valid for SPEC
• Component naming convention

Error Codes:

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:

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

Report Output

## Upstream Drift Analysis

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

| Upstream Document | SPEC Reference | Cached Hash | Current Hash | Status | Severity |
|-------------------|----------------|-------------|--------------|--------|----------|
| REQ-03.yaml | @req Section req_implementations | sha256:abc1... | sha256:def4... | DRIFT | Warning |
| CTR-03-001.yaml | @ctr endpoints | sha256:ghi7... | sha256:ghi7... | FRESH | - |

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

Review Score Calculation

Scoring Formula:

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

1. First Review: Creates SPEC-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 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

Version History

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.