Documentation Cleaner
Consolidate redundant documentation while preserving 100% of valuable content.
Scope guardrails
| Use this skill when… | Avoid/hand off when… |
|---|---|
| Docs overlap, multiple sources of truth, or total length is unwieldy (>500 lines). | Task is "make docs match code changes" → run update-docs first. |
| Reviewers/authors want a single canonical location. | Typos/format-only edits → lightweight fixes, no consolidation. |
| You need to dedupe without losing value. | Archives/historical records must stay intact → archive separately instead of consolidating. |
| You plan to replace duplicates with stubs pointing to the canonical doc. | None |
Core Principle
Critical evaluation before deletion. Never blindly delete. Analyze each section's unique value before proposing removal. The goal is reduction without information loss.
Workflow
Phase 1: Discovery
- Identify all documentation files covering the topic
- Count total lines across files
- Map content overlap between documents
Phase 2: Value Analysis
For each document, create a section-by-section analysis table:
| Section | Lines | Value | Reason |
|---|---|---|---|
| API Reference | 25 | Keep | Unique endpoint documentation |
| Setup Steps | 40 | Condense | Verbose but essential |
| Test Results | 30 | Delete | One-time record, not reference |
Value categories:
- Keep: Unique, essential, frequently referenced
- Condense: Valuable but verbose
- Delete: Duplicate, one-time, self-evident, outdated
See references/value_analysis_template.md for detailed criteria.
Phase 3: Consolidation Plan
Propose target structure:
Before: 726 lines (3 files, high redundancy)
After: ~100 lines (1 file + reference in CLAUDE.md)
Reduction: 86%
Value preserved: 100%Phase 4: Execution
- Create the canonical consolidated document with all valuable content
- Replace redundant source files with short stubs that point to the canonical doc (default; delete only if repo policy explicitly allows)
- Update references (CLAUDE.md, README, imports, in-repo links)
- Verify no broken links using the link-audit checklist
See references/stub_template.md for stub patterns and references/link-audit.md for the audit checklist.
Value Preservation Checklist
Before finalizing, confirm preservation of:
- Essential procedures (setup, configuration)
- Key constraints and gotchas
- Troubleshooting guides
- Technical debt / roadmap items
- External links and references
- Debug tips and code snippets
Anti-Patterns
| Pattern | Problem | Solution |
|---|---|---|
| Blind deletion | Loses valuable information | Section-by-section analysis first |
| Keeping everything | No reduction achieved | Apply value criteria strictly |
| Multiple sources of truth | Future divergence | Single authoritative location |
| Orphaned references | Broken links | Update all references after consolidation |
Output Artifacts
A successful cleanup produces:
- Consolidated document - Single source of truth
- Value analysis - Section-by-section justification
- Before/after metrics - Lines reduced, value preserved
- Stub list - Paths of replaced files pointing to canonical doc
- Link audit summary - Broken link check results and fixes applied