| name | doc-test-alignment |
| description | Verify that committed docs (README.md, CLAUDE.md, SKILL.md descriptions) still describe what the code and tests actually do. Use at the end of a plan, before PR creation, or when the user says "check doc-test alignment", "verify docs", or "do the docs still match the code". STUB — `scripts/check.sh` exits with a not-yet-implemented error today; the contract for what it will do lives in this file.
|
doc-test-alignment (stub)
This skill is a stub. The real workflow is intentionally not yet implemented —
the file exists so that steward verify can find it and so contributors who
land here know it is on the roadmap, not forgotten.
How to run
scripts/check.sh is the entry point. Today it prints a not-yet-implemented
notice and exits non-zero. When the workflow lands, the script will gate
PR-readiness on the alignment contract below; until then, treat any green
exit code from this script as a bug.
What it will check
The skill is the contract for four narrow alignments. README.md command
examples must still execute against the current checkout and produce output
that matches the surrounding prose. The "build/test/publish" command lines in
CLAUDE.md must do the same. For each .claude/skills/<name>/, the SKILL.md
description frontmatter must agree with what the scripts under
scripts/ actually do — surfacing disagreements (e.g. SKILL.md claims the
skill bumps versions but scripts/ has no bump script). And for each test,
the test name should still describe the assertions the test makes — flagging
drift where the name advertises a feature the assertions no longer touch.
Why it ships as a stub
Each of those four checks is independently non-trivial. Shipping a partial
implementation would either silently pass when it shouldn't, or false-positive
on intentional doc-vs-code differences. The right path is to land the checks
one at a time, with their own tests, behind a
steward verify --check doc-test-alignment flag. The parent verbs (verify,
doctor) are named in the "Roadmap" section of CLAUDE.md; the broader
sibling-pattern contract lives in docs/sibling-pattern.md.
What this stub guarantees today
- The skill directory exists, so
steward verify's skills-convention check
finds the standard layout (SKILL.md + scripts/ with an entry-point).
scripts/check.sh is the entry-point script, satisfying the steward skills
convention requirement that every skill ships an executable script.- This
SKILL.md is the contract for what the skill will do — when the
implementation lands, it must satisfy this description or the description
must move first.
