yq-doc-maintenance

Documentation Governance

Maintain a coherent documentation system whose claims have clear owners and can be checked against the project. Start with ownership and structure; edit prose only after the source of truth is known. This skill covers Markdown, READMEs, tutorials, runbooks, reference docs, decision records, postmortems, JSDoc, and code comments. Use yq-technical-writing for sentence-level coverage and clarity, and yq-remove-reasoning-leaks for authoring-session residue. If the audit exposes implementation, test, or gate complexity rather than a documentation-ownership problem, invoke $yq-simplify-code for that candidate instead of hiding a behavior change inside documentation cleanup.

This is guidance, not a universal folder layout. Discover and preserve the repository's own documentation contract.

Establish the documentation contract

1. Confirm the requested scope and whether the task is an audit, a proposal, or an authorized edit. Use the narrowest defensible scope from the request and current diff; do not silently expand a focused task into a repository-wide rewrite.
2. Snapshot the audit identity: repository, checkout or worktree, branch, revision, dirty state, and applicable instructions. Recheck it before reporting. If the worktree changes during the audit, stop combining observations, anchor completed findings to the captured revision, and list later changes as uninspected.
3. Read applicable AGENTS.md, CLAUDE.md, CONTEXT.md, root and package READMEs, documentation indexes, architecture/decision records, contribution guides, and CI or package scripts that validate docs.
4. Identify excluded or derivative areas: third-party sources, generated catalogs, build output, recorded fixtures, snapshots, vendored documentation, and frozen archives. Edit an owner before regenerating a derivative artifact.
5. Record how this repository expresses intended behavior, observed behavior, rationale, and process. Code or runtime evidence can establish what happens; it does not automatically overrule a current product specification. When those disagree, label the mismatch instead of silently choosing one.