playbooks

home / skills / daymade / claude-code-skills / docs-cleaner

docs-cleaner skill

/docs-cleaner

This skill consolidates redundant documentation while preserving all valuable content, reducing bloat without sacrificing essential details.

npx playbooks add skill daymade/claude-code-skills --skill docs-cleaner

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.9 KB
---
name: docs-cleaner
description: Consolidates redundant documentation while preserving all valuable content. This skill should be used when users want to clean up documentation bloat, merge redundant docs, reduce documentation sprawl, or consolidate multiple files covering the same topic. Triggers include "clean up docs", "consolidate documentation", "too many doc files", "merge these docs", or when documentation exceeds 500 lines across multiple files covering similar topics.
---

# Documentation Cleaner

Consolidate redundant documentation while preserving 100% of valuable content.

## 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

1. Identify all documentation files covering the topic
2. Count total lines across files
3. 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

1. Create consolidated document with all valuable content
2. Delete redundant source files
3. Update references (CLAUDE.md, README, imports)
4. Verify no broken links

## 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:

1. **Consolidated document** - Single source of truth
2. **Value analysis** - Section-by-section justification
3. **Before/after metrics** - Lines reduced, value preserved
4. **Updated references** - CLAUDE.md or README with pointer to new location

Overview

This skill consolidates redundant documentation while preserving all valuable content. It reduces documentation sprawl by merging overlapping files into a single authoritative document and producing a clear justification for every change. Use it to shrink doc volume without losing essential procedures, constraints, or troubleshooting guidance.

How this skill works

The skill scans a set of documentation files, counts lines, and maps overlap to identify redundancy. It produces a section-by-section value analysis (Keep, Condense, Delete), a consolidation plan with before/after metrics, and a consolidated document that retains 100% of valuable information. Finally, it updates references and verifies no broken links remain.

When to use it

  • When documentation exceeds ~500 lines across multiple files on the same topic
  • When you hear triggers like “clean up docs”, “consolidate documentation”, or “merge these docs”
  • When multiple files create conflicting or duplicate guidance
  • When onboarding or maintenance is slowed by doc sprawl
  • When you need a single source of truth for a component or feature

Best practices

  • Perform a section-by-section value analysis before any deletion
  • Categorize content as Keep, Condense, or Delete with explicit reasons
  • Preserve all essential procedures, constraints, and troubleshooting items
  • Create clear before/after metrics and store the value analysis alongside the consolidated doc
  • Update all references and verify links to avoid orphaned pointers
  • Keep one authoritative file and add short pointers for historical records

Example use cases

  • Merge three overlapping setup guides into one concise setup & troubleshooting document
  • Condense verbose API reference files into a compact reference with preserved examples
  • Remove one-time test reports while preserving test patterns and expected outputs
  • Consolidate multiple HOWTOs into a single workflow with per-step rationale and gotchas
  • Reduce onboarding docs from many files into a single quickstart plus deeper reference

FAQ

How do you ensure nothing important is lost?

Every section gets a documented value analysis with explicit reasons. Items marked Delete are reviewed for one-time or outdated status and preserved elsewhere if needed.

Will links and imports break after consolidation?

No—updating references is part of execution. The skill verifies links and updates in-project pointers to the consolidated document.

Can I keep historical files for audit?

Yes. The plan can archive original files with pointers rather than immediate deletion, maintaining traceability while reducing active documentation.