Documentation Audit

Comprehensive audit to ensure zero documentation drift across ALL docs, agent instructions, and config files.

Principle: Use existing scripts instead of ad-hoc grep commands. Never create temporary audit scripts — all checks are covered by the repo's tooling and test suite.

Complete Documentation Inventory

Layer 1: Primary Docs

Layer 2: Agent Instructions

Layer 3: Root-Level Files

Phase 0 — File Tree Completeness (Structural Drift)

Why this is Phase 0: Missing files in file maps is the #1 drift source. Check this first.

Compare the actual file tree against every file-map section in agent instruction files and docs:

1. List actual files: ls src/, ls config/, ls docs/
2. Cross-check against file maps in:

1. Every real file/directory must appear in all file maps. Flag any missing entries.

Phase 1 — Identify What Changed

git diff --stat
git log --oneline -10

Classify the change type:

• Config change → schema, examples, stats references may be stale
• UI/layout change → styling guide, layout constraints may be stale
• New feature → user flow, architecture, changelog, roadmap may be stale
• File added/removed/renamed → file trees, path references may be stale
• Agent rule change → must propagate to ALL agent instruction files

Phase 2 — Run Automated Drift Checks

Do not use ad-hoc grep commands or create temporary scripts for checks that existing tooling already covers.

# Run all automated tests
npm test

# [FILL: Add any project-specific drift/stats scripts here]

Verify policy alignment:

• Agent docs do not hardcode mutable totals as static source-of-truth values
• If a snapshot number is documented, it is clearly labeled with snapshot context/date

Phase 3 — Verify Path Conventions

# Find references to potentially stale paths
grep -rn "[FILL: old-path-prefix]" docs/ .agent/ .claude/ .github/ AGENTS.md CLAUDE.md --include="*.md"

Current correct conventions:

• [FILL: Path convention 1 — e.g. "No leading / or ./ in asset paths"]
• [FILL: Path convention 2 — e.g. "Assets at assets/{name}.ext"]

Phase 4 — Verify Config ↔ Code Consistency

Use existing tooling — do not write ad-hoc scripts for these checks.

All automated checks from Phase 2 cover config consistency. If they all pass, this phase is done.

Phase 5 — Cross-Check Agent Files

5a. File map sync (structural)

Verify all files/directories in the repo are listed in the agent file maps (see Phase 0).

5b. Fact consistency

All agent instruction files must agree on:

Phase 6 — Workflow & Skill Consistency

• .agent/workflows/doc-audit.md — This workflow is itself still accurate? (meta-audit)
• .claude/skills/doc-audit/SKILL.md — Same as above?
• .github/pull_request_template.md — Contains explicit docs/ADR/policy alignment gates?
• [FILL: Any project-specific workflows to check]

Phase 7 — Update CHANGELOG

If any doc fixes were made:

### Fixed
- Documentation drift: updated [specific counts/paths/conventions] across [N] files

Change → Doc Impact Matrix

Drift Severity