/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:
    - generate-claudemd
    - codebase-overview

Documentation Sync Checker Skill

Deterministic 4-phase drift detector that compares the filesystem against README entries. 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.

Optional flags: `--auto-fix` (experimental, requires explicit opt-in), `--strict` (exit code 1 on issues), `--format json` (machine-readable output for CI/CD).

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | documentation work | `documentation-structure.md` | Loads detailed guidance from `documentation-structure.md`. | | before/after doc-update examples: adding skill docs, removing deprecated agent docs | `examples.md` | Loads detailed guidance from `examples.md`. | | wiring the checker into CI, pre-commit, or auto-fix mode | `integration-guide.md` | Loads detailed guidance from `integration-guide.md`. | | expected table and list formats per README file | `markdown-formats.md` | Loads detailed guidance from `markdown-formats.md`. | | which docs must list which tools; sync score and deprecation rules | `sync-rules.md` | Loads detailed guidance from `sync-rules.md`. |

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

**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-linting/` has `name: code-linting`)

Agents (`agents/*.md`):

• File has valid YAML frontmatter with `name` field
• 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 README files and compare with discovered tools. Each tool type has a primary documentation file: skills belong in `docs/skills.md`, agents in `agents/README.md`, commands in `commands/README.md`.

**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

**Step 2: Parse each documentation file**

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

| File | Format | What to Extract | |------|--------|-----------------| | `docs/skills.md` | Markdown table | Name, Description, Command, Hook columns | | `agents/README.md` | Table or list | Name, Description fields | | `commands/README.md` | Markdown list | /command-name - Description items | | `README.md` | Inline references | Pattern-match `skill: X`, `/command`, `agent-name` | | `docs/REFERENCE.md` | Section headers | `### tool-name` headers with descriptions |

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

For each documentation file, 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**

• All 5 documentation files found and parsed (warn if any missing)
• No parse errors on table/list structures
• Tool names extracted from each file

**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 e