docs-guard

Docs-guard reviews generated or changed documentation before it ships, covering READMEs, API references, docstrings, PHPDoc/JSDoc, changelogs, tutorials, and doc sites. Its core principle is that documentation is a set of checkable claims about a codebase, and its job is to verify every referenced function, flag, endpoint, config key, and code sample against the source, catch docs-versus-code drift, and strip filler and unverifiable claims. It exists because AI agents tend to document from memory of how APIs usually look rather than from the code in front of them, producing authoritative-sounding but sometimes incorrect docs that readers cannot distinguish from verified ones.

The skill operates in three modes: guard-pass mode (the recommended default) verifies claims against the source and runs a self-check after docs are generated; live mode verifies before writing by reading the actual implementation first; and review mode walks references/review-checklist.md against target docs to produce a findings report with file:line evidence without rewriting unless asked. It first adapts to the project by reading agent instructions like CLAUDE.md or AGENTS.md and any style guide, then applies ten rules grouped by severity. Must-fix accuracy rules require every referenced symbol to exist, every code sample to work, documentation of actual (not intended) behavior, and no unverifiable claims. Versioning and drift rules require explicit versions and that a code change owes a docs change (grep the docs for old symbols). Should-fix substance rules remove filler and slop, discourage paraphrasing upstream docs, and require examples to cover failure paths. A structure rule requires navigation, tables of contents, and links to resolve. A self-check before delivery confirms every symbol was verified against the source, samples would run on a clean machine, and links resolve, and a defined reporting format leads with Rule 1-4 findings.

The skill targets developers and agents who need to ship accurate technical documentation, and is best used reactively after docs are written or edited, after code changes documented behavior, or before publishing. Supporting references cover the verification procedure, code-sample rules, docstring rules, the review checklist, and source citations. It explicitly does not do production code review (use clean-code-guard), test review (use test-guard), marketing copy or blog posts, prose editing of non-technical writing, or documentation-site theming.