health

Check Documentation Health

Give the contributor a fast, honest read on the state of their documentation, and one clear place to start.

This is the orientation command: the first thing to run after installing the plugin, and the periodic pulse check afterward. It is not the deep audit. Health is fast and whole-repo, ends in a scorecard and a single recommendation, and should feel like a knowledgeable colleague skimming the docs and telling you what they'd fix first. /docs-assist:audit is the follow-up when someone wants the full findings list.

The optional argument ($ARGUMENTS) is the docs directory. Detect it if not given.

Process

1. Establish What the Project Is

Speed matters more than completeness here. Sample; do not read everything.

• Read the README and manifest to learn what the project does and who uses it.
• For a large repo, fan out the doc-recon subagent and work from its project map instead of reading inline.
• Resolve .docs-assist/ config if present (${CLAUDE_PLUGIN_ROOT}/skills/docs-assist/reference/config-resolution.md).

2. Score Four Dimensions

Assess each dimension from samples and cheap signals, not an exhaustive pass. Rate each solid, needs work, or missing, with one line of evidence.

• Coverage: does a doc exist for each thing users need? Compare the project's main features and entry points against the docs that exist. A missing README, quickstart, or install doc outweighs any number of polish issues.
• Freshness: are the docs still true? In a git repo, run the decay detector (node ${CLAUDE_PLUGIN_ROOT}/assets/ci/docs-decay.mjs) and read its ranked queue: it scores every doc on related-source churn since the doc last changed, last-verified age, doc age, and open sme-attested claims, deterministically and with the reasons shown. It costs about two git calls per doc; for a docs set large enough that a full scan would break the fast-scorecard promise (hundreds of files), pass it the highest-traffic subdirectory instead of the whole tree, and say that's what you scanned. Outside a git repo, fall back to comparing doc modification dates and last-verified frontmatter against the code by hand. Either way, a doc describing a heavily changed area, untouched since, is the signal. The decay detector ranks which docs are worth a real trace; it does not perform one. It scores churn, not correctness, so a "solid" rating here means "nothing looks stale," not "every claim was checked against the code" (see ${CLAUDE_PLUGIN_ROOT}/skills/docs-assist/reference/claim-verification.md); if the ranking surfaces genuinely high-risk docs, that is itself a "needs work" finding pointing at the full audit, not something health resolves on its own.
• Consistency: do the docs agree with each other? If .docs-assist/config.yml lists lint.tools, run them against the docs directory first and fold real findings (heading-level skips, missing blank lines, untagged fences, prose issues) straight into the rating; don't approximate what a configured linter would catch by reading files instead. Then spot-check what linters can't see: example values against each other and .docs-assist/reference.yml's example-variable entries, terms against its term entries (see ${CLAUDE_PLUGIN_ROOT}/skills/docs-assist/reference/terminology.md), and heading and frontmatter conventions across sibling docs. If lint.tools isn't set, note that as part of the rating rather than silently doing everything by hand.
• Findability: can a reader (or an AI tool) get to the right doc? Check for an llms.txt and whether it matches the docs, cross-references between related docs, and orphan docs nothing links to.