docs-hygiene

Read-only audit of whether a doc earns its existence: could a fresh agent re-derive it from code, config, and structure? One verdict per file: delete, convert-to-pointer, keep-as-derivation-cache, or keep-owns-facts. Use when: 'is this doc worth keeping', 'audit doc value', 'derivability', 'could an agent figure this out itself', 'should this doc exist', 'this doc just restates the code', 'prune redundant docs', 'does this doc earn its maintenance'. Line-level noise is /docs-hygiene:audit-noise.

Audit and remediate skill-encapsulation violations. External citations reaching into private surfaces inside `.claude/skills/<X>/` or `plugins/<plugin>/skills/<X>/` (marketplace monorepos) beyond the slash invocation. Use when: 'audit encapsulation', 'find skill leaks', 'skill boundary violation', 'who is reaching into <skill>', 'check skill boundaries', 'public API drift', or before refactoring a skill.

Read-only audit of a docs tree's file names against a configured casing rule: proposes a name per offender, classifies every reference to it, refuses case-only collisions, and writes the plan realign-file-names applies. Use when: 'audit file names', 'are our doc filenames consistent', 'plan a docs rename', 'which files break the naming rule', 'find every reference to this doc', 'rename the docs tree', 'lower-kebab the docs folder', 'what would a docs rename touch'. Renames nothing.

Read-only audit of tracked markdown for nine noise shapes, like historical citations, ghost refs, why-this-file-exists preambles, tracker back-references, and conversational residue, tiered by treatment. Use when: 'audit markdown noise', 'declutter', 'check for stale citations', 'find ghost refs', 'classify preamble', 'strip conversational residue from a doc', 'find negations without a positive', 'sweep a rule/skill/convention doc for noise'. Code comments: /code-tidying:audit-comment-residue.

Read-only progressive-disclosure audit of agent-facing instruction markdown: grades each file against always-loaded, invocation-loaded, and on-demand tiers and flags split and disclosure defects. Use when: 'progressive disclosure', 'split this file', 'this file is too long', 'too much context', 'mixed concerns', 'hub and spoke', 'is my CLAUDE.md too big', 'audit context loading', 'what should always be loaded'. In-page noise is /docs-hygiene:audit-noise; frontmatter QA is /skill-quality:check.

Compress markdown by dropping flavor, filler, hedging, and articles while keeping every directive, qualifier, threshold, and example, behind a semantic-diff subagent that reverts any meaning loss. Use when: 'compress this doc', 'tighten markdown', 'cut prose', 'shorten without losing meaning', 'trim onboarding doc'. Actions: default and audit (read-only dry run). Not session compaction (/compact), markdown noise (/docs-hygiene:audit-noise), or SSOT consolidation (/docs-hygiene:extract-ssot).

Deduplicate repeated markdown (rule files, skill bodies, ADRs, docs) into one named source of truth and migrate every call site to cite it by exact heading. Use when the same prose, literal, or concept recurs across files: 'DRY this prose', 'extract a shared rule', 'single source of truth for X', a value-bump diff touching several files. Below the Rule of Three it offers only non-abstracting remedies and refuses a new SSOT artifact.

Emit the file-name gate into a consuming repository: a standalone bash checker plus its own test suite, with the casing rule, roots, and exemptions inlined from the resolved docs-hygiene configuration, and optionally the path-scoped rule file. The emitted pair carries no dependency on this plugin at run time. Refuses to overwrite without --force, and states the wiring it deliberately leaves to the consumer. Use when: 'generate the file-name gate', 'add a CI check for doc filenames', 'enforce the naming rule', 'emit the naming checker', 'we need a gate for this convention', 'write the file-names rule file', or after docs-hygiene:setup apply has written the configuration.

Apply a file-name rename plan one file at a time, one human acceptance each: git mv, rewrite only the reference shapes each citing file's tier allows, rebuild generated records, and sweep for stragglers. Refuses a blanket yes, a range, a glob, and 'all'. Use when: 'apply the rename plan', 'apply FN-...', 'do the docs renames', 'rename these files', 'execute the file-name findings', 'accept that rename'. Needs a plan from docs-hygiene:audit-file-names; never commits.

Sweep stale references after a rename, including forms token-only grep misses (slash-tokens, paths, chain prose, table rows, frontmatter globs). Use when: 'rename X to Y', 'I renamed X', 'audit rename', 'find stale refs', 'check for stragglers', 'after git mv', 'sweep references', 'rename impact preview', 'find half-renamed state', 'broken refs after rename', 'pre-PR rename check'. A whole tree against a casing rule is docs-hygiene:audit-file-names.

Verify or configure the docs-hygiene file-name skills for this repository: `check` resolves all three configuration layers, reports which layer supplied each key, and verifies that the casing regex compiles, every tier names a known form, every generated file's regenerator resolves, the team layer is tracked, and the personal overlay is ignored; `apply` writes the tracked `.claude/docs-hygiene.json` team layer per key, idempotently, and edits no other file. Use when: 'set up docs-hygiene', 'configure the file-name rule', 'is docs-hygiene configured', 'which casing rule is in effect', 'change the docs naming regex', 'add a frozen tier', 'docs-hygiene setup', or an audit reports a configuration layer it could not read.

Write agent-consumed markdown: CLAUDE.md or AGENTS.md content, .claude/rules files, agent-loaded reference docs, navigation pointers, and doc-plus-pointer extractions. Use when: 'add this to CLAUDE.md', 'write a rule for X', 'write this up for the agent', 'add a pointer to the docs', 'move this section into its own doc', 'draft an AGENTS.md section', or any edit to markdown an agent loads. SKILL.md authoring is playbooks:skill-authoring; human-facing docs are docs-hygiene:write-for-humans.

Write human-facing prose: READMEs, RFCs, design docs, release notes, changelog entries, tutorials, how-tos, reference, explanations, per the project style guide. Use when: 'write the README', 'draft an RFC', 'write the release notes', 'write a how-to for X', 'document this for users', 'write this up for humans', 'what kind of doc is this', 'is this the right kind of doc', 'make this doc readable', 'this doc reads like a machine wrote it'. Agent-loaded markdown: docs-hygiene:write-for-agents.