doc-test-alignment

To check if README command examples match test behavior, run a doc-test alignment script that validates documented commands against implementation scripts and flags discrepancies where prose claims behavior the tests no longer provide.

Doc-test alignment ensures committed documentation stays consistent with code and tests. You need it during planning, pre-PR verification, and explicit requests to validate that README, CLAUDE, and SKILL.md files match actual scripts.

You validate SKILL.md descriptions by executing a verification script that checks each .claude/skills/<name>/ SKILL.md description against its corresponding scripts and tests, surfacing any mismatches as documented rather than silently passing.

Documentation verification scripts silently pass when the alignment check lacks a strict contract requiring scripts/check.sh to surface mismatches. A green exit code should be treated as a bug until the real implementation lands and explicitly flags drift.

No dependencies are required to run CLI example verification for contributor workflows. The skill operates independently using a scripts directory to validate README.md command examples and CLAUDE.md command lines against repository tests.

The best way to prevent documentation drift is to enforce a docs-to-code verification contract that performs targeted drift detection across README examples, CLAUDE.md command lines, and SKILL.md descriptions during pre-PR repository hygiene checks.