/docs-sync-checker

name: docs-sync-checker
description: "Detect documentation drift against filesystem state."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
routing:
  triggers:
    - "check doc drift"
    - "sync documentation"
    - "stale docs"
    - "documentation drift"
    - "README outdated"
  category: documentation
  pairs_with:
    - toolkit
    - assessment

Documentation Sync Checker Skill

Deterministic 4-phase drift detector that compares the filesystem against each tool type's primary doc: `docs/skills.md`, `docs/routing-map.md`, and `docs/REFERENCE.md`. Each phase (Scan, Cross-Reference, Detect, Report) has a gate that must pass before proceeding. The skill produces a sync score (percentage of tools properly documented) and actionable fix suggestions for every detected issue.

This skill checks documentation presence and absence only -- it does not judge description quality, generate documentation content, resolve merge conflicts, validate cross-references, or track when drift occurred. Suggested fixes use YAML descriptions verbatim; content generation and quality assessment require different skills.

Report flags: `--strict` (exit code 1 on issues), `--format json` (machine-readable output).

---

Instructions

Phase 1: SCAN

**Goal**: Discover all skills, agents, and commands in the repository filesystem. All discovery (file existence checks, YAML parsing, markdown extraction) must be deterministic -- no AI judgment on content quality.

**Step 1: Run the scan script**

python3 skills/meta/docs-sync-checker/scripts/scan_tools.py --repo-root $HOME/vexjoy-agent --output /tmp/scan_results.json

**Step 2: Validate discovery results**

For each tool type, verify:

Skills (`skills/**/SKILL.md`):

• File has opening `---` and closing `---` YAML delimiters
• YAML contains non-empty `name` and `description` fields
• `name` field matches directory name (e.g., `skills/code-quality/code-quality/` has `name: code-quality`)
• A skill with `promoted_to`, or one reached through a symlink (private), is scanned but not expected in the catalog

Agents (`agents/*.md`):

• File has valid YAML frontmatter with `name` field; a file without frontmatter (`agents/base-instructions.md`) is not an agent
• Filename (without .md) matches YAML `name` value

Commands (`commands/**/*.md`):

• File exists as markdown in commands/ directory
• Namespaced commands in subdirectories (e.g., `commands/code/cleanup.md`) are detected

**Step 3: Validate the docs routing catalog**

Every `docs/*.md` file (outside `archive/` and `images/`) carries frontmatter with `summary` and `read_when` — the on-demand load triggers for docs, matching what `skills/INDEX.json` gives skills.

python3 scripts/docs-catalog.py --check

Exit 1 means a doc is missing frontmatter; add `summary` and `read_when` to that file. `python3 scripts/docs-catalog.py` (no flags) prints the catalog table; `--json` emits it machine-readable.

**Step 4: Count and verify**

## Scan Results
Skills found: [N]
Agents found: [N]
Commands found: [N]
YAML errors: [N] (must be 0 to proceed)

**Gate**: All tools discovered, all YAML valid, counts >0 for each type, docs catalog check exits 0. Proceed only after the gate passes.

Phase 2: CROSS-REFERENCE

**Goal**: Extract documented tools from each type's primary doc and compare with discovered tools. Targets live in `PRIMARY_DOCS` in `scripts/parse_docs.py`; `scripts/validate.py` fails if one is missing.

**Step 1: Run the documentation parser**

python3 skills/meta/docs-sync-checker/scripts/parse_docs.py --repo-root $HOME/vexjoy-agent --scan-results /tmp/scan_results.json --output /tmp/issues.json

**Step 2: Parse each primary doc**

These are the documentation files to check -- no others:

| File | Tool type | Maintained by | What to Extract | |------|-----------|---------------|-----------------| | `docs/skills.md` | Skills | `scripts/generate-skills-doc.py` | First cell of every table row: `` `skill-name` `` | | `docs/routing-map.md` | Agents | `scripts/generate-routing-map.py` | First cell of each `## AGENTS` table row: `agent-name` | | `docs/REFERENCE.md` | Commands | Hand-written | First cell of each `## Slash Commands` table row: `` `/command` `` | | `README.md` | Mentions only | Hand-written | `/command` and `*-engineer` mentions; recorded, never flagged |

**Step 3: Build documented-tools registry**

For each primary doc, collect the set of tool names found. This creates a mapping of `{file -> [tool_names]}` that Phase 3 will compare against the filesystem scan.

**Step 4: Verify parse completeness**

• Every primary doc found and parsed; a missing one exits 2 and stops the run. Never create a placeholder doc to get past it: fix `PRIMARY_DOCS` and this table.
• Entry counts are non-zero for each type

**Gate**: All documentation files parsed without errors. Proceed only after the gate passes.

Phase 3: DETECT

**Goal**: Compare discovered tools with documented tools to identify drift. This is a point-in-time snapshot -- it cannot tell you when drift occurred, only that it exists now.

**Step 1: Compute set differences**

For each tool type and its primary documentation file:

• `missing = filesystem_tools - documented_tools` (tools that exist but are not documented)
• `stale = documented_tools - filesystem_tools` (documented tools that no longer exist -- users waste time trying to invoke non-existent tools, so always flag these)

**Step 2: Categorize and assign severity**

Severity reflects user impact: missing entries mean tools are undiscoverable and stale entries waste time.

| Category | Condition | Severity | |----------|-----------|----------| | Missing Entry | Tool in filesystem, not in its primary doc | HIGH | | Stale Entry | Tool in a primary doc, not in filesystem | MEDIUM | | Incomplete Entry | Documentation missing required fields | LOW |

**Step 3: Record issue details**

For ea