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 presence, absence, and version alignment 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.
example-driven tasks	examples.md	Loads detailed guidance from examples.md.
tasks related to this reference	integration-guide.md	Loads detailed guidance from integration-guide.md.
tasks related to this reference	markdown-formats.md	Loads detailed guidance from markdown-formats.md.
tasks related to this reference	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 name, description, and version 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: 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. 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 skills/README.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
skills/README.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: Check version consistency

For tools that appear in both sets, compare:

• YAML version field vs. documented version (if version is documented)
• Flag mismatches where YAML is authoritative source of truth

Step 3: Categorize and assign severity

Severity reflects user impact: missing entries mean tools are undiscoverable, stale entries waste time, version mismatches cause confusion.

Category	Condition	Severity
Missing Entry	Tool in filesystem, not in primary README	HIGH
Stale Entry	Tool in README, not in filesystem	MEDIUM
Version Mismatch	YAML version differs from documented	LOW
Incomplete Entry	Documentation missing required fields	LOW

Step 4: Record issue details

For each issue, capture: tool type, tool name, tool path, affected documentation file(s), severity, and suggested fix action.

Gate: All issues categorized with severity. Proceed only after the gate passes.

Phase 4: REPORT

Goal: Generate human-readable report with actionable fix suggestions. Report facts concisely -- show data, not self-congratulatory descriptions. Target 100% sync score; even one missing entry erodes trust in all documentation.

Step 1: Run the report generator

python3 skills/meta/docs-sync-checker/scripts/generate_report.py --issues /tmp/issues.json --output /tmp/sync-report.md

Step 2: Verify report structure

Report must include these sections:

1. Summary -- Total tools, issue counts by severity, sync score

   sync_score = (total_tools - total_issues) / total_tools * 100
   

2. HIGH Priority: Missing Entries -- For each missing tool, provide the exact markdown row/item to add to the appropriate README file

3. MEDIUM Priority: Stale Entries -- For each stale tool, identify the file and line to remove

4. LOW Priority: Version Mismatches -- For each mismatch, show YAML version (authoritative) vs. documented version

5. Files Checked -- List each documentation file with count of tools parsed from it

Step 3: Validate actionability

Every issue in the report must have a concrete suggested fix. No issue should say "review manually" without specifying what to review and where. The fix should enable a single-commit resolution -- tool files and documentation entries should be added/removed together.

Step 4: Report format for missing entries

For each missing skill, generate a suggested table row:

| skill-name | Description from YAML | `skill: skill-name` | - |

For each missing agent, generate a suggested table row:

| agent-name | Description from YAML |

For each missing command, generate a suggested list item:

- `/command-name` - Description from command file

Step 5: Cleanup

Remove any helper scripts and debug outputs created during execution.

Gate: Report generated with actionable suggestions for every issue.

Examples

Example 1: New Skill Missing from README

User created skills/my-new-skill/SKILL.md but forgot to update skills/README.md. Actions:

1. SCAN discovers my-new-skill in filesystem
2. CROSS-REFERENCE parses skills/README.md, does not find my-new-skill
3. DETECT flags as HIGH severity missing entry
4. REPORT suggests exact table row to add to skills/README.md

Example 2: Removed Agent Still Documented

User deleted agents/old-agent.md but agents/README.md still lists it. Actions:

1. SCAN does not find old-agent in filesystem
2. CROSS-REFERENCE finds old-agent in agents/README.md
3. DETECT flags as MEDIUM severity stale entry
4. REPORT suggests removing the row from agents/README.md

Example 3: Version Bump Without Doc Update

User updated version: 2.0.0 in skills/code-quality/code-linting/SKILL.md but docs/REFERENCE.md still shows Version: 1.5.0. Actions:

1. SCAN reads YAML version as 2.0.0
2. CROSS-REFERENCE reads documented version as 1.5.0 from docs/REFERENCE.md
3. DETECT flags as LOW severity version mismatch
4. REPORT suggests updating version line in docs/REFERENCE.md to 2.0.0

Example 4: Batch Changes After Refactor

User created 3 new skills and deleted 2 old ones in a refactoring PR. Actions:

1. SCAN discovers 3 new skills in filesystem, does not find 2 removed skills
2. CROSS-REFERENCE finds 2 stale entries and 3 absent entries in skills/README.md
3. DETECT flags 3 HIGH (missing) + 2 MEDIUM (stale) issues
4. REPORT provides exact table rows to add and identifies rows to remove

Error Handling

Error: "YAML Parse Error"

Cause: Invalid frontmatter -- missing --- delimiters, tabs instead of spaces, or missing required fields Solution:

1. Check file has opening --- on line 1 and closing --- after YAML block
2. Verify no tab characters in YAML (spaces only)
3. Confirm required fields present: name, description, version
4. Validate manually: head -20 {file_path} and check syntax

Error: "Documentation File Not Found"

Cause: Expected README file does not exist at expected path Solution:

1. Verify --repo-root path is correct
2. Check that skills/README.md, agents/README.md, commands/README.md exist
3. If file is legitimately missing, create a placeholder with the expected table/list header
4. Re-run scan after creating placeholder

Error: "No Tools Discovered"

Cause: Wrong --repo-root path, empty directories, or no SKILL.md files Solution:

1. Verify the repo root path points to the correct repository
2. Confirm skills/, agents/, commands/ directories exist and are not empty
3. Check that skill directories contain SKILL.md (not just other files)
4. Run with --debug flag for verbose discovery output

Error: "Markdown Parse Error"

Cause: Table missing separator row, mismatched column counts, or malformed list items Solution:

1. Check table has header row, separator row (|---|---|), and data rows
2. Verify all rows have the same number of pipe-delimited columns
3. For lists, verify consistent format: - /command - Description
4. See references/markdown-formats.md for complete format specifications

---

References

• ${CLAUDE_SKILL_DIR}/references/documentation-structure.md: Documentation file matrix, required fields per location, cross-reference requirements
• ${CLAUDE_SKILL_DIR}/references/markdown-formats.md: Expected table/list formats for each README file, parsing rules, common formatting errors
• ${CLAUDE_SKILL_DIR}/references/sync-rules.md: Synchronization rules, severity levels, deprecation handling, namespace rules
• ${CLAUDE_SKILL_DIR}/references/examples.md: Before/after examples for adding, removing, updating, and batch documentation changes
• ${CLAUDE_SKILL_DIR}/references/integration-guide.md: CI/CD setup, pre-commit hooks, auto-fix mode, JSON output, workflow integration