doc-tasks-reviewer

Purpose

Comprehensive content review and quality assurance for Task Breakdown (TASKS) documents. This skill performs deep content analysis beyond structural validation, checking task completeness, SPEC alignment, implementation contracts, dependency accuracy, and identifying issues that require manual review.

Layer: 11 (TASKS Quality Assurance)

Upstream: TASKS (from doc-tasks-autopilot or doc-tasks)

Downstream: None (final QA gate before code implementation)

When to Use This Skill

Use doc-tasks-reviewer when:

• After TASKS Generation: Run immediately after doc-tasks-autopilot completes
• Manual TASKS Edits: After making manual changes to TASKS
• Pre-Implementation: Before starting code implementation
• Sprint Planning: When assessing task readiness for development
• Periodic Review: Regular quality checks on existing TASKS

Do NOT use when:

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

Skill vs Validator: Key Differences

Review Workflow

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

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

    D --> F0[0. Structure Compliance]
    E --> F0
    F0 --> F0C{BLOCKING Check}
    F0C -->|FAIL| BLOCK[STOP - Fix Structure First]
    F0C -->|PASS| F[Run Review Checks]

    subgraph Review["Review Checks"]
        F --> G[1. Task Completeness]
        G --> H[2. SPEC Alignment]
        H --> I[3. Implementation Contracts]
        I --> J[4. Dependency Accuracy]
        J --> K[5. Task Atomicity]
        K --> L[6. AI Implementation Hints]
        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 (12/12) – BLOCKING

Validates TASKS follows the mandatory nested folder rule.

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

Required Structure:

Error Codes:

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

1. Task Completeness

Validates all tasks have required elements.

Required Elements:

• Task ID
• Description
• Acceptance criteria
• Priority
• Estimated complexity
• Dependencies

Error Codes:

2. SPEC Alignment

Validates tasks trace to SPEC requirements.

Scope:

• Every task maps to SPEC component/method
• Full SPEC coverage achieved
• No orphaned tasks
• Implementation order logical

Error Codes:

3. Implementation Contracts

Validates Section 7-8 implementation contracts.

Scope:

• Protocol interfaces defined
• Exception hierarchies documented
• State machine contracts present
• Data models specified
• DI interfaces defined

Error Codes:

4. Dependency Accuracy

Validates task dependencies are correct.

Scope:

• Dependencies exist
• No circular dependencies
• Blocking dependencies identified
• External dependencies documented

Error Codes:

5. Task Atomicity

Validates tasks are appropriately sized.

Scope:

• Single responsibility
• Independently implementable
• Clear completion criteria
• Reasonable scope

Error Codes:

6. AI Implementation Hints

Validates AI-friendly implementation guidance.

Scope:

• File paths specified
• Method signatures suggested
• Import statements provided
• Test patterns documented

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 TASKS.NN.TT.SS format
• Element type codes valid for TASKS (18, 30)
• Task naming convention

Error Codes:

9. Upstream Drift Detection (Mandatory Cache)

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

The drift cache is mandatory. All drift detection operations require cache initialization and maintenance.

Purpose: Identifies stale TASKS content that may not reflect current SPEC and TSPEC documentation. When SPEC documents (methods, interfaces, components) or TSPEC documents (test cases, coverage requirements) change, the TASKS may need updates to maintain implementation alignment.

Scope:

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

Drift Cache File (MANDATORY)

Location: docs/11_TASKS/.drift_cache.json

Schema:

{
  "schema_version": "1.0",
  "cache_created": "2026-02-10T17:00:00Z",
  "cache_updated": "2026-02-10T17:00:00Z",
  "tasks_files": {
    "TASKS-03_f3_observability.md": {
      "tasks_version": "1.0",
      "tasks_updated": "2026-02-10T14:30:00",
      "last_review": "2026-02-10T17:00:00",
      "upstream_hashes": {
        "../../09_SPEC/SPEC-03.yaml": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
        "../../09_SPEC/SPEC-03.yaml#methods": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
        "../../09_SPEC/SPEC-03.yaml#components": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
        "../../10_TSPEC/TSPEC-03.md": "d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
        "../../10_TSPEC/TSPEC-03.md#test_cases": "e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4"
      },
      "upstream_mtimes": {
        "../../09_SPEC/SPEC-03.yaml": "2026-02-08T10:15:00",
        "../../10_TSPEC/TSPEC-03.md": "2026-02-09T16:45:00"
      }
    }
  }
}

Cache Management:

• Cache file is created on first review if not present
• Cache is updated after each successful review
• Missing cache triggers REV-D006 error
• Corrupted cache triggers cache rebuild with warning

Three-Phase Detection Algorithm

Phase 1: Cache Validation

1. Check if .drift_cache.json exists
   - If missing → ERROR REV-D006: "Drift cache not initialized"
   - If corrupted → Rebuild cache, emit WARNING

2. Validate cache schema version
   - If outdated → Migrate cache to current schema

3. Load TASKS entry from cache
   - If TASKS not in cache → Initialize entry

Phase 2: Reference Extraction

1. Extract all upstream references from TASKS:
   - @spec: tags → [path, section anchor]
   - @tspec: tags → [path, section anchor]
   - Links to ../09_SPEC/ → [path]
   - Links to ../10_TSPEC/ → [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. Get file modification time (mtime)

Phase 3: Drift Comparison

1. For each upstream reference:
   a. Compare mtime > cached mtime
      - If newer → flag as TIMESTAMP_DRIFT
   b. Compute SHA-256 hash of content
   c. Compare to cached hash
      - If differs → flag as CONTENT_DRIFT
   d. Calculate change percentage
      - If > 20% → flag as SUBSTANTIAL_DRIFT

2. Update cache with current values after comparison

Hash Calculation

Full File Hash:

import hashlib

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

Section Hash (for anchor references):

def compute_section_hash(file_path: str, anchor: str) -> str:
    """Compute SHA-256 hash of specific section."""
    content = extract_section(file_path, anchor)
    return hashlib.sha256(content.encode('utf-8')).hexdigest()

def extract_section(file_path: str, anchor: str) -> str:
    """Extract section content from markdown/yaml by anchor."""
    # For markdown: Find ## {anchor} heading to next ## heading
    # For yaml: Find {anchor}: key to next top-level key
    ...

Error Codes

Report Output

## Upstream Drift Analysis

**Cache Status**: Valid (last updated: 2026-02-10T17:00:00Z)

| Upstream Document | TASKS Reference | Last Modified | Cached Modified | Hash Match | Days Stale | Severity |
|-------------------|-----------------|---------------|-----------------|------------|------------|----------|
| SPEC-03.yaml | @spec Section methods | 2026-02-08T10:15:00 | 2026-02-05T09:00:00 | No | 3 | Warning |
| SPEC-03.yaml | @spec components | 2026-02-10T14:30:00 | 2026-02-05T09:00:00 | No | 5 | Warning |
| TSPEC-03.md | @tspec test_cases | 2026-02-09T16:45:00 | 2026-02-05T09:00:00 | Yes | 4 | Info |

**Recommendation**: Review upstream SPEC/TSPEC changes and update TASKS if methods, components, or test cases have changed.

**Cache Updated**: 2026-02-10T17:00:00Z (3 entries refreshed)

Auto-Actions

• Create .drift_cache.json if not present (first review)
• Update cache with current hashes and mtimes after review
• Add [DRIFT] marker to affected @spec/@tspec 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 TASKS
/doc-tasks-reviewer TASKS-03

# Review TASKS by path
/doc-tasks-reviewer docs/11_TASKS/TASKS-03_f3_observability.md

# Review all TASKS
/doc-tasks-reviewer all

Output Report

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

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

File Naming: TASKS-NN.R_review_report_vNNN.md

Location: Inside the TASKS nested folder: docs/11_TASKS/TASKS-NN_{slug}/

Versioning Rules

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

Example:

docs/11_TASKS/TASKS-03_f3_observability/
├── TASKS-03_f3_observability.md
├── TASKS-03.R_review_report_v001.md    # First review
├── TASKS-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-tasks-autopilot

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

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

Related Skills

Version History