Documentation Quality Assurance

Prevent documentation rot through systematic audits, automated validation, and pipeline-enforced quality gates.

Scope: Inheritable skill. Covers drift detection, preflight validation, count elimination, link integrity, 5-pass quality pipeline, staleness detection, and large-project organization.

Complements: The Documentarian agent uses this skill as its knowledge foundation. This skill is the "what" — the agent is the "who".

The Count Problem

Hardcoded counts in documentation drift silently:

Count Elimination Rules

Canonical Count Sources

When a count is needed, always derive it from the file system:

Docs-as-Architecture

Documentation is a load-bearing part of the system, not a separate artifact:

Document Header Pattern

Comprehensive Metadata Headers

Operational documentation (regression checklists, deployment guides, QA procedures, release workflows) should include comprehensive headers that provide complete context at-a-glance.

Minimal Header (4 lines) — Insufficient:

**Date**: 2026-02-14
**Status**: In Progress
**Purpose**: Verify v5.7.1 UI features
**Method**: Install and test

Enhanced Header (10+ lines) — Comprehensive:

**Version**: 5.7.1
**Date**: 2026-02-14
**Status**: ⚠️ PENDING UI VERIFICATION — WebP avatars regenerated, awaiting restart + testing
**Testing Mode**: CP2 Contingency (Local Install)
**VSIX Size**: 9.44 MB (426 files)
**Key Changes**: Enterprise auth removed, WebP avatars optimized (144×144, 92% reduction)

**Purpose**: Local install verification of all v5.7.1 visual identity + UI features
**Method**: Install VSIX locally, restart VS Code, test in current workspace (CP2 contingency)
**Expected Outcome**: All 9 test sections pass → DoD criterion #4 complete → Ready to publish

Header Field Guidelines

Rule: Include enough metadata that anyone can understand the document's context without reading the body. Operational docs reviewed during incidents need at-a-glance clarity.

5-Pass Quality Pipeline

Run these passes in sequence on any document suite:

Rule: Don't merge passes — each pass has a single focus. Multi-focus reviews miss more than single-focus reviews applied sequentially.

Preflight Validation

Automated Checks

Run before every release or documentation change:

# Example preflight validation script
function Test-DocQuality {
    $errors = @()
    
    # Check 1: All markdown links resolve
    Get-ChildItem -Recurse -Filter "*.md" | ForEach-Object {
        $content = Get-Content $_.FullName -Raw
        $links = [regex]::Matches($content, '\[([^\]]+)\]\(([^)]+)\)')
        foreach ($link in $links) {
            $target = $link.Groups[2].Value
            if ($target -notmatch '^https?://' -and $target -notmatch '^#') {
                $resolved = Join-Path (Split-Path $_.FullName) $target
                if (-not (Test-Path $resolved)) {
                    $errors += "Broken link in $($_.Name): $target"
                }
            }
        }
    }
    
    # Check 2: No orphan files in docs folder
    # Check 3: Required sections present in each doc type
    # Check 4: Version strings match package.json
    
    return $errors
}

Pre-Implementation Cross-Reference Sweep

Before adding any new file, check what already references the concept:

1. •Grep for the concept name across all docs
2. •Identify which files will need updating
3. •Create the new file AND update all references in a single commit

Anti-pattern: Creating a new skill/agent and updating only one reference document. Every catalog, index, and count needs updating simultaneously.

Link Integrity

Link Audit Protocol

Orphan Detection

# Find markdown files not referenced by any other markdown file
$allMd = Get-ChildItem -Recurse -Filter "*.md" | Select-Object -ExpandProperty Name
$referenced = @()
Get-ChildItem -Recurse -Filter "*.md" | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    $links = [regex]::Matches($content, '\]\(([^)]+\.md)')
    foreach ($link in $links) {
        $referenced += Split-Path $link.Groups[1].Value -Leaf
    }
}
$orphans = $allMd | Where-Object { $_ -notin $referenced }

Staleness Detection

Last Validated Dates

Add validation dates to critical documents:

<!-- Last Validated: 2026-02-12 by Documentarian audit -->

Staleness Tiers

Drift Detection During Maintenance

During regular maintenance cycles (meditation, dream, release prep):

1. •Compare document claims against current reality
2. •Flag any numeric drift (counts, versions, dates)
3. •Check if referenced files still exist
4. •Verify code examples still compile/execute
5. •Update Last Validated timestamp after review

Large Project Organization

15+ File Threshold

When a documentation folder exceeds 15 files, introduce numbered chapter folders:

docs/
├── 01-getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── configuration.md
├── 02-architecture/
│   ├── overview.md
│   ├── components.md
│   └── data-flow.md
├── 03-operations/
│   ├── deployment.md
│   ├── monitoring.md
│   └── troubleshooting.md
└── README.md              # Index/TOC

Rules:

• •Numbered prefixes ensure consistent ordering across all tools
• •Each chapter folder has 3-7 files (not 1, not 20)
• •Root README.md serves as table of contents with links to all sections
• •Flat structure is fine for < 15 files

Multi-Audience Documentation

Audience Matrix

Every doc suite serves multiple readers:

Rule: Each document should declare its audience. A document trying to serve all audiences well serves none of them well.

Ship First, Document After (Threshold)

Anti-pattern: Blocking a release to write perfect docs. Ship with minimal docs (README + quick start), then iterate.

Doc Audit Checklist

Run this 7-item checklist for any documentation review:

CHANGELOG Best Practices