repo-docs

Codex form of the /repo:docs command. Other commands appear as $repo-<verb> skills. Helper scripts and .claude/ paths below are relative to the repository root and exist when the Claude Code surface is installed alongside this one.

$repo-docs — Documentation Check

The canonical documentation-health command. Verify that the repo's docs still describe the repo that exists — not the one that existed three refactors ago.

This is the single entry point for docs work. It covers three layers:

1. Content accuracy — does the prose still match how things actually work? (unique to this command)
2. README structure — do file trees and directory listings match disk? (delegates to [[readme]])
3. Cross-references — do internal links and paths still resolve? (delegates to [[links]])

$repo-readme and $repo-links remain callable on their own when you only want that one layer. Reach for $repo-docs when you want the whole picture.

Usage

$repo-docs                     # Full repo — apply safe fixes, report as you go
$repo-docs docs/               # Scope to one subtree
$repo-docs README.md           # Check a single doc
$repo-docs --ask               # Review findings and confirm before applying

The optional path argument scopes every layer the same way, exactly as [[readme]] and [[links]] scope on their own.

What It Checks

1. Content Accuracy

This is the semantic layer that structural checks miss — prose that parses fine and links that resolve fine, but describes behavior that has since changed. Read the docs against the actual repo state and flag drift:

• Feature / command tables that list capabilities the repo no longer has, or omit ones it gained. For a repo with .claude/commands/, cross-check every documented command against the files that actually exist, in both directions.
• CHANGELOG currency — recent commits (features, breaking changes, renames) that landed with no corresponding CHANGELOG entry. Compare the top entry's date/version against git log since then.
• Code examples & snippets in docs that reference symbols, flags, file paths, or commands that no longer exist. Verify each referenced identifier resolves in the current tree.
• Described workflows — step-by-step instructions (install, build, usage) that name scripts, targets, or flags. Confirm they still exist and still take the arguments shown.
• Version / count claims — "supports 12 commands", "requires Node 18", hardcoded numbers that drift as the repo changes.