doc-ctr-reviewer

Purpose

Comprehensive content review and quality assurance for Data Contract (CTR) documents. This skill performs deep content analysis beyond structural validation, checking contract completeness, dual-file consistency (MD + YAML), OpenAPI compliance, REQ alignment, and identifying issues that require manual review.

Layer: 8 (CTR Quality Assurance)

Upstream: CTR (from doc-ctr-autopilot or doc-ctr)

Downstream: None (final QA gate before SPEC generation)

When to Use This Skill

Use doc-ctr-reviewer when:

• After CTR Generation: Run immediately after doc-ctr-autopilot completes
• Manual CTR Edits: After making manual changes to CTR
• Pre-SPEC Check: Before running doc-spec-autopilot
• API Changes: When external APIs are modified
• Periodic Review: Regular quality checks on existing CTRs

Do NOT use when:

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

Skill vs Validator: Key Differences

Review Workflow

flowchart TD
    A[Input: CTR Path] --> B[Load CTR Files]
    B --> C{MD + YAML Present?}

    C -->|Both| D[Load Both Files]
    C -->|Single| E[Load Available File]

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

    subgraph Review["Review Checks"]
        F --> G[1. Dual-File Consistency]
        G --> H[2. OpenAPI Compliance]
        H --> I[3. REQ Alignment]
        I --> J[4. Endpoint Coverage]
        J --> K[5. Security Definition]
        K --> L[6. Placeholder Detection]
        L --> M[7. Naming Compliance]
        M --> M2[8. Upstream Drift Detection]
    end

    M2 --> 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 CTR follows the mandatory nested folder rule.

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

Required Structure:

Error Codes:

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

1. Dual-File Consistency

Validates MD and YAML files are synchronized.

Scope:

• Endpoint definitions match
• Schema definitions aligned
• Version numbers consistent
• Descriptions synchronized

Error Codes:

2. OpenAPI Compliance

Validates YAML follows OpenAPI 3.x specification.

Scope:

• Valid OpenAPI version
• Required fields present
• Schema types correct
• Response codes documented

Error Codes:

3. REQ Alignment

Validates CTR traces to REQ requirements.

Scope:

• Every endpoint maps to REQ
• External API requirements covered
• Interface contracts complete

Error Codes:

4. Endpoint Coverage

Validates all expected endpoints documented.

Scope:

• CRUD operations complete
• Error endpoints defined
• Health check endpoints present
• Versioning strategy documented

Error Codes:

5. Security Definition

Validates security schemes documented.

Scope:

• Authentication method defined
• Authorization scopes documented
• Security schemes in OpenAPI
• Rate limiting documented

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 CTR.NN.TT.SS format
• Element type codes valid for CTR (16, 17, 20)
• Contract naming convention

Error Codes:

8. Upstream Drift Detection (Mandatory Cache)

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

The drift cache is mandatory. All CTR reviewer operations must maintain the drift cache to enable reliable change detection across sessions.

Purpose: Identifies stale CTR content that may not reflect current REQ documentation. When REQ documents (interface requirements, external API specifications) change, the CTR may need updates to maintain alignment.

Scope:

• @req: tag targets (REQ documents)
• Traceability section upstream artifact links
• Any markdown links to ../07_REQ/ or REQ source documents

Drift Cache File (MANDATORY)

Location: docs/08_CTR/.drift_cache.json

Schema:

{
  "schema_version": "1.0",
  "last_updated": "2026-02-10T17:00:00",
  "documents": {
    "CTR-03-001": {
      "ctr_path": "docs/08_CTR/CTR-03-001_provider_api/CTR-03-001.md",
      "ctr_updated": "2026-02-10T14:30:00",
      "upstream_hashes": {
        "docs/07_REQ/REQ-03.md": {
          "full_hash": "a1b2c3d4e5f6...",
          "section_hashes": {
            "interfaces": "1a2b3c4d...",
            "external_apis": "5e6f7g8h..."
          },
          "last_checked": "2026-02-10T17:00:00"
        }
      }
    }
  }
}

Three-Phase Detection Algorithm

Phase 1: Cache Initialization
  1. Check if docs/08_CTR/.drift_cache.json exists
  2. If not exists → create with schema_version: "1.0"
  3. Load cache into memory

Phase 2: Reference Extraction and Hash Comparison
  1. Extract all upstream references from CTR:
     - @req: tags → [path, section anchor]
     - Links to ../07_REQ/ → [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 #3)
     c. Compute SHA-256 hash of full file content
     d. If section anchor specified → compute section hash
     e. Compare hashes against cached values
     f. If hash differs → flag as DRIFT

Phase 3: Cache Update
  1. Update upstream_hashes with current values
  2. Set last_checked timestamp
  3. Write cache to disk
  4. Report cache status in output

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 anchor-specific tracking):

sed -n '/^## Section Name/,/^## /p' <file_path> | head -n -1 | 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-10T17:00:00

| Upstream Document | CTR Reference | Hash Status | Last Modified | Days Stale | Severity |
|-------------------|---------------|-------------|---------------|------------|----------|
| REQ-03.md | @req interfaces | CHANGED | 2026-02-08 | 3 | Warning |
| REQ-03.md | Traceability | UNCHANGED | 2026-02-05 | 0 | OK |

**Drift Summary**:
- Total References: 5
- Unchanged: 3
- Changed: 2
- New (uncached): 0

**Recommendation**: Review upstream REQ changes and update CTR if interface requirements have changed.

Auto-Actions:

• Create .drift_cache.json if not exists
• Update cache with current hashes after every review
• Add [DRIFT] marker to affected @req 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 CTR
/doc-ctr-reviewer CTR-03-001

# Review CTR by path
/doc-ctr-reviewer docs/08_CTR/CTR-03-001_provider_api/

# Review all CTRs
/doc-ctr-reviewer all

Output Report

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

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

File Naming: CTR-NN-SSS.R_review_report_vNNN.md

Location: Inside the CTR nested folder: docs/08_CTR/CTR-NN_{slug}/

Versioning Rules

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

Example:

docs/08_CTR/CTR-03-001_provider_api/
├── CTR-03-001.md
├── CTR-03-001.yaml
├── CTR-03-001.R_review_report_v001.md    # First review
├── CTR-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-ctr-autopilot

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

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

Related Skills

Version History