Documentation Consolidator

Discover all documentation in a project, analyze for redundancy and contradictions, propose a consolidation plan, then execute it with user approval.

Follow all 4 steps sequentially. Do NOT execute changes without user approval at Step 3.

Step 1: Discover

Find every documentation file in the project.

Glob for docs -- search for **/*.md, **/*.mdx, **/*.txt, **/*.rtf (exclude node_modules/, .git/, vendor/, target/, dist/, build/, __pycache__/, archive/).
List what you found -- output each file with its path. Note how many docs exist total.
Flag monorepo READMEs separately -- if the project has READMEs inside subdirectories (packages, modules, services), list them in their own group. These need extra care in Step 3.

Step 2: Map & Categorize

Read each doc and build a landscape table for the user.

For each doc, note:

Path
Type: readme / guide / reference / changelog / config / adr / agent-config / other
What it covers (brief summary)
Overlaps with other docs (list paths)

Then identify:

Duplicated sections -- same content in multiple files (e.g., setup steps in README + CONTRIBUTING + docs/getting-started)
Contradictions -- different files say different things about the same topic

Present the map:

## Documentation Map: {project}

**Documents found:** {count}

| Path | Type | Covers | Overlaps With |
|------|------|--------|---------------|
| README.md | readme | setup, overview | CONTRIBUTING.md (setup) |
| ... | ... | ... | ... |

### Duplicated Content
- **Setup instructions** appear in: README.md, CONTRIBUTING.md, docs/getting-started.md

### Contradictions
- README.md says `npm start`, CONTRIBUTING.md says `yarn dev`

Ask the user using AskUserQuestion with multiSelect: true:

Are any of these docs auto-generated or externally published (should not be edited)?
Are any docs off-limits for other reasons?

Step 3: Plan Structure

Propose where docs should live and what changes to make.

For each doc, assign an action:

Action	Meaning
MERGE	Combine multiple docs into one target
MOVE	Relocate to a better path (uses `git mv`)
UPDATE	Rewrite or refresh in place
CREATE	New doc (usually CLAUDE.md)
ARCHIVE	Move to `archive/` -- never delete
SKIP	Leave as-is, with reason

Present the plan:

## Consolidation Plan

| # | Action | Target | Details |
|---|--------|--------|---------|
| 1 | MERGE | docs/setup.md | README setup + CONTRIBUTING setup |
| 2 | UPDATE | README.md | Remove duplicated setup, link to docs/setup.md |
| 3 | CREATE | CLAUDE.md | Commands, architecture, conventions |
| 4 | ARCHIVE | docs/old-api.md | Superseded by docs/api.md |
| 5 | SKIP | LICENSE | No changes needed |

Hard gate: Ask the user to approve, modify, or reject using AskUserQuestion:

Approve and execute (Recommended)
Modify -- user adjusts specific actions
Reject -- stop, no changes

If uncertain about any monorepo README or module-level doc, ask the user explicitly before including it in the plan.

Do NOT proceed to Step 4 without explicit approval.

Step 4: Execute & Summarize

Execute approved actions in order: ARCHIVE first, then MERGE, then UPDATE, then CREATE, then MOVE.

Execution rules:

ARCHIVE -- git mv {path} archive/{path}. Add a header: 
MERGE -- Read all sources. Combine content -- keep all unique information, deduplicate overlapping sections, resolve contradictions (prefer fresher source; ask user if unclear).
UPDATE -- Apply specified changes.
CREATE -- For CLAUDE.md: commands first, terse, structured, under 300 lines. For other docs: scannable headings, examples over prose.
MOVE -- git mv so git tracks history.

After all actions, grep for broken internal links (](, href=) pointing to moved/archived files and fix them.

Present results:

## Consolidation Complete

### Changes

| Before | After | What Changed |
|--------|-------|-------------|
| README.md (setup + overview) | README.md (overview only) | Setup moved to docs/setup.md |
| docs/old-api.md | archive/docs/old-api.md | Archived |
| (new) | CLAUDE.md | Created with commands, architecture |

### What's Next
1. **Review changes** -- walk through each modified file
2. **Undo** -- revert all changes (`git checkout`)
3. **Commit** -- commit as a single commit

Style Guide

General principle: Same information in exactly one place. Links replace duplication.

CLAUDE.md (agent-optimized):

Commands section first -- build, test, lint, deploy
Terse: Run tests: npm test not a paragraph about the test framework
Structured: bullet lists and tables, not prose
Under 300 lines total

Human docs:

Scannable headings -- a reader skimming should understand the structure
Examples over explanations -- show, don't tell
One doc per concern -- setup, API, architecture each get their own file
Reference config files instead of duplicating their content

Monorepo READMEs:

Be careful -- module READMEs often serve a real purpose for that module's users
Keep module-specific content in module READMEs
Only consolidate if content is truly duplicated project-wide info
When in doubt, ask the user

Rules

Never delete docs -- archive to archive/ if obsolete
Don't remove content when merging -- combine duplicated sections, keep unique info from each source
If uncertain whether a change is safe, ask the user
Use git mv for all moves so git tracks history
Always present the summary at the end with before/after changes