doc-tspec-reviewer

Purpose

Comprehensive content review and quality assurance for Test Specification (TSPEC) documents. This skill performs deep content analysis beyond structural validation, checking test coverage across all 6 types (UTEST, ITEST, STEST, FTEST, PTEST, SECTEST), SPEC alignment, test case completeness, and identifying issues that require manual review.

Layer: 10 (TSPEC Quality Assurance)

Upstream: TSPEC (from doc-tspec-autopilot or doc-tspec)

Downstream: None (final QA gate before implementation)

When to Use This Skill

Use doc-tspec-reviewer when:

• After TSPEC Generation: Run immediately after doc-tspec-autopilot completes
• Manual TSPEC Edits: After making manual changes to TSPEC
• Pre-Implementation: Before starting test implementation
• Coverage Review: When assessing test coverage completeness
• Periodic Review: Regular quality checks on existing TSPECs

Do NOT use when:

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

Skill vs Validator: Key Differences

Review Workflow

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

    C -->|Yes| D[Parse TSPEC Structure]
    C -->|No| E[Report Format Error]

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

    subgraph Review["Review Checks"]
        F --> G[1. Test Coverage Targets]
        G --> H[2. SPEC Alignment]
        H --> I[3. Test Case Completeness]
        I --> J[4. Test Data Definition]
        J --> K[5. Test Environment Requirements]
        K --> L[6. Edge Case 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 TSPEC follows the mandatory nested folder rule.

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

Required Structure:

Error Codes:

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

1. Test Coverage Targets

Validates coverage targets are met.

Coverage Targets:

• Unit Tests (UTEST): >= 80%
• Integration Tests (ITEST): >= 70%
• Smoke Tests (STEST): Critical paths
• Functional Tests (FTEST): >= 85%

Error Codes:

2. SPEC Alignment

Validates tests trace to SPEC requirements.

Scope:

• Every SPEC method has corresponding tests
• All interfaces tested
• Error scenarios covered
• Thresholds validated in tests

Error Codes:

3. Test Case Completeness

Validates test cases have all required elements.

Required Elements:

• Test ID
• Description
• Preconditions
• Test steps
• Expected results
• Postconditions

Error Codes:

4. Test Data Definition

Validates test data is properly defined.

Scope:

• Test data sets documented
• Boundary values included
• Invalid data sets present
• Data setup/teardown defined

Error Codes:

5. Test Environment Requirements

Validates environment specifications present.

Scope:

• Environment requirements documented
• Dependencies listed
• Configuration specified
• Resource requirements defined

Error Codes:

6. Edge Case Coverage

Validates edge cases and error conditions tested.

Scope:

• Boundary conditions tested
• Null/empty input handling
• Timeout scenarios
• Concurrent access cases

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 TSPEC.NN.TT.SS format
• Element type codes valid for TSPEC (40, 41, 42, 43, 44, 45)
• Test case naming convention

Error Codes:

9. Upstream Drift Detection (Mandatory Cache)

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

The drift cache is mandatory. All TSPEC reviews must maintain and validate against the drift cache to ensure test specifications remain synchronized with SPEC changes.

Purpose: Identifies stale TSPEC content that may not reflect current SPEC documentation. When SPEC documents (methods, interfaces, data models) change, the TSPEC may need updates to maintain test coverage alignment.

Scope:

• @spec: tag targets (SPEC documents)
• Traceability section upstream artifact links
• Any markdown links to ../09_SPEC/ source documents

Drift Cache File (MANDATORY)

Location: docs/10_TSPEC/.drift_cache.json

Schema:

{
  "cache_version": "2.0",
  "created": "2026-02-10T17:00:00Z",
  "last_validated": "2026-02-10T17:00:00Z",
  "documents": {
    "TSPEC-03": {
      "tspec_path": "docs/10_TSPEC/TSPEC-03_f3_observability.md",
      "tspec_hash": "sha256:abc123...",
      "last_updated": "2026-02-10T14:30:00Z",
      "upstream_refs": {
        "SPEC-03.yaml": {
          "path": "docs/09_SPEC/SPEC-03_f3_observability.yaml",
          "content_hash": "sha256:def456...",
          "section_hashes": {
            "methods": "sha256:ghi789...",
            "interfaces": "sha256:jkl012...",
            "data_models": "sha256:mno345..."
          },
          "last_validated": "2026-02-10T14:30:00Z"
        }
      }
    }
  }
}

Three-Phase Detection Algorithm

Phase 1: Cache Initialization

IF .drift_cache.json does not exist:
    1. Create cache file with schema version 2.0
    2. Scan all TSPEC documents in docs/10_TSPEC/
    3. For each TSPEC:
       a. Extract upstream SPEC references
       b. Compute content hashes for TSPEC
       c. Compute content hashes for each upstream SPEC
       d. Store in cache
    4. Report: "Cache initialized with N TSPEC documents"

Phase 2: Drift Detection

FOR each TSPEC being reviewed:
    1. Load cached hashes for this TSPEC
    2. For each upstream SPEC reference:
       a. Compute current hash of SPEC document
       b. Compare to cached hash
       c. IF hashes differ:
          - Flag as DRIFT
          - Compute section-level hashes to identify changed sections
          - Calculate change percentage
    3. Check timestamp: SPEC mtime > TSPEC last_updated
    4. Aggregate drift findings by severity

Phase 3: Cache Update

AFTER successful review (score >= threshold):
    1. Update content hashes for reviewed TSPEC
    2. Update upstream SPEC hashes
    3. Set last_validated timestamp
    4. Write updated cache to disk
    5. Report: "Cache updated for TSPEC-NN"

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):

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**: Valid | Last validated: 2026-02-10T14:30:00Z

| Upstream Document | TSPEC Reference | Cached Hash | Current Hash | Change % | Severity |
|-------------------|-----------------|-------------|--------------|----------|----------|
| SPEC-03.yaml | @spec methods | sha256:abc1... | sha256:xyz9... | 15% | Warning |
| SPEC-03.yaml | @spec interfaces | sha256:def4... | sha256:def4... | 0% | OK |

### Changed Sections Detail

**SPEC-03.yaml#methods** (15% change):
- Lines 45-67: Method signature changed
- Lines 120-135: New parameter added

**Recommendation**: Review upstream SPEC changes and update TSPEC test cases for modified methods.

Auto-Actions:

• Initialize .drift_cache.json if missing (Phase 1)
• Update cache with current hashes after successful review (Phase 3)
• Add [DRIFT] marker to affected @spec tags in review report
• Generate drift summary with section-level detail

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 TSPEC
/doc-tspec-reviewer TSPEC-03

# Review TSPEC by path
/doc-tspec-reviewer docs/10_TSPEC/TSPEC-03_f3_observability.md

# Review all TSPECs
/doc-tspec-reviewer all

Output Report

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

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

File Naming: TSPEC-NN.R_review_report_vNNN.md

Audit Wrapper Compatibility: doc-tspec-audit can emit TSPEC-NN.A_audit_report_vNNN.md as preferred fixer input while reviewer-native .R_review_report_vNNN.md remains supported.

Location: Inside the TSPEC nested folder: docs/10_TSPEC/TSPEC-NN_{slug}/

Versioning Rules

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

Example:

docs/10_TSPEC/TSPEC-03_f3_observability/
├── TSPEC-03_f3_observability.md
├── TSPEC-03.R_review_report_v001.md    # First review
├── TSPEC-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-tspec-autopilot

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

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

Related Skills

Version History