---
name: docs-cleanup
description: Tidy and improve a project's documentation tree — relocate design/plan files misfiled as docs, reconcile docs that have drifted from the code they describe, fix dead links and stale references, and flag (never silently delete) duplicates and intentional mirrors. Use when asked to clean up docs, organize the docs folder, fix doc drift or dead links, separate plans from documentation, or audit documentation for staleness.
allowed-tools: Read, Grep, Glob, Bash, Edit, Write
context: fork
---

Keep the documentation tree honest: every file is either **living
documentation** (a reference a reader or agent consults) or a **plan** (a design
or build spec describing work to do), nothing is a stale copy, and no doc
contradicts the code it describes. Apply the safe, unambiguous fixes; surface
the judgment calls. Code is the source of truth — when a doc and the code
disagree, the doc is wrong unless the doc is a deliberate spec for unbuilt work.

This is documentation hygiene, not code review. For source-code structure use
the architecture audit; for bugs use the code review.

## Orient first

Don't assume layout — discover it:

- The **docs directory** (e.g. `docs/`): living references — architecture,
  guidelines, agent/usage docs, ADRs.
- The **plan directory** (where the project keeps work-item markdown) and its
  staging subfolders. Plans that are designs/specs rather than queued work
  belong in a non-executed staging subfolder (commonly `designs/`, alongside any
  existing `audits/` folder). Check how the runner picks up plans (often a
  top-level `*.md` glob), so you know which subfolders are safe parking spots
  that won't be auto-executed.
- The **canonical sources** a doc might mirror or import: a global
  conventions/config file, a checked-in `CLAUDE.md`, code modules.

## What to check and fix

1. **Misfiled plans.** A file in the docs directory whose body is a plan —
   headers like "Plan —", "Status: build spec / proposed / design", phase
   checklists, "what changes / what dies" tables, "definition of done" — is work
   tracking, not reference documentation. **Move it** into the plan directory's
   designs staging subfolder. Use `git mv` for tracked files, plain `mv` for
   untracked ones. Preserve the filename.

2. **Drift from code.** Read the doc's concrete claims and check them against the
   code: enum members and their count ("the four X" when the enum has two),
   module names, file paths, CLI flags, config keys, function names. When the
   code has moved on, **edit the doc to match the code**. Cite the `file:line`
   you verified against. If it's genuinely ambiguous which is right (the doc may
   be an intended-but-unbuilt spec), flag it instead of guessing.

3. **Cross-doc contradiction.** When two docs state the same fact differently,
   one is stale. Reconcile to the code; if no code arbitrates, keep the version
   in the referenced/loaded doc and fix the other. Per the single-source
   principle, a fact should live in exactly one place — if a doc restates rules
   that belong to a canonical file it imports, cut the restatement and point to
   the source.

4. **Dead references and links.** Grep each doc for paths and `[...](...)` links;
   flag and fix references to files that were moved or deleted (including ones
   *this* cleanup just moved). Update the pointer to the new location.

5. **Completed-migration staleness.** A migration/refactor doc whose target state
   is now the present tense describes history, not a plan. Note it — propose
   archiving it (move to the designs staging folder as a record) rather than
   leaving it in docs as if still pending.

## Never delete blind — verify, then surface

A file that is byte-identical to a canonical source is **not automatically junk**
— it is often a deliberate in-repo mirror so the content travels with the repo.
Before proposing any deletion:

- Confirm identity (`diff -q`) **and** that nothing references the copy
  (`grep -rn`), **and** check project memory/notes for an intentional-mirror
  decision.
- If it's referenced or a known intentional mirror: **keep it, report why** — do
  not delete.
- Only when it is a true orphan (identical, unreferenced, no mirror intent) do
  you propose removal — and you *propose* it in the report; you do not delete a
  file you did not create without the user confirming.

The same caution applies to any doc a human authored: surface a recommendation,
let the human pull the trigger on irreversible removal.

## Process

1. Read-only first: classify every file in the docs tree as DOC or PLAN, and
   list candidate fixes by category above.
2. Apply the **safe, reversible** fixes directly: plan relocations (`git mv`),
   drift edits that make a doc match verified code, dead-link updates.
3. **Propose** (do not perform) the judgment calls: deletions, archiving a
   completed migration, reconciling a contradiction where code can't arbitrate.

## Output

Report what you did and what you propose, grouped:

```
MOVED    <old path> → <new path>          (reason)
FIXED    <file:line>                       (drift/link: was → now, verified against <code file:line>)
PROPOSE  <action> <file>                   (reason; needs confirmation because <irreversible/judgment>)
KEPT     <file>                            (looked like a dup/stale but is <intentional mirror/referenced>)
```

End with a one-line verdict: `CLEAN` if the tree needed no changes, otherwise a
count of moved / fixed / proposed.