| name | design-prune |
| description | Remove historical cruft from design docs. Use when docs accumulate outdated content, after major refactorings, or when preparing for releases. |
| allowed-tools | Read, Edit, Glob, Bash(grep *), Bash(date *) |
| context | fork |
| agent | design-doc-agent |
Design Documentation Pruning
Removes historical cruft from design documentation by detecting and removing
outdated content, update histories, and deprecated sections while preserving
essential historical context.
Overview
This skill cleans up design documentation by identifying historical content
patterns, calculating staleness scores, generating pruning plans, and
applying safe removal strategies to keep docs focused on current state
while preserving important context.
Quick Start
Basic pruning:
/design-docs:design-prune effect-type-registry
Aggressive pruning:
/design-docs:design-prune effect-type-registry --aggressive
Dry-run (preview only):
/design-docs:design-prune effect-type-registry --dry-run
Parameters
Required
module: Module name to prune (or "all" for all modules)
Optional
doc: Specific document to prune (default: all docs in module)aggressive: Remove all historical content (default: false, conservative mode)dry-run: Preview changes without applying (default: false)
Workflow
High-level pruning process:
- Parse parameters to determine module, document, and pruning mode
- Load design.config.json to get module paths and pruning configuration
- Read design document and parse structure, sections, and content types
- Detect historical content using pattern matching for historical markers
- Calculate staleness score based on age, markers, redundancy, and
cross-references
- Generate pruning plan with specific actions (remove, condense, archive,
preserve)
- Apply pruning according to mode (conservative/aggressive/dry-run)
- Update frontmatter with last-pruned date and reduction percentage
- Validate result to ensure document still valid after pruning
- Generate pruning report with summary and actions taken
For detailed implementation steps, see supporting documentation below.
Supporting Documentation
When you need detailed information, load the appropriate supporting file:
For Detailed Workflow
See instructions.md for:
- Complete step-by-step pruning workflow
- Historical content detection algorithms
- Staleness scoring formulas and categories
- Pruning plan generation
- Pruning execution (conservative, aggressive, dry-run)
- Frontmatter updates
- Validation procedures
- Report generation
- Edge case handling (cross-references, partial historical, conflicting dates)
Load when: Performing pruning or need implementation details
For Pruning Strategies
See pruning-strategies.md for:
- Remove entirely strategy (when and how)
- Condense to summary strategy
- Archive strategy
- Preserve with marker strategy
- Strategy selection criteria
- Safety checks and rollback
Load when: Need strategy details or deciding which approach to use
For Content Patterns
See content-patterns.md for:
- Historical content markers (keywords, dates, strikethrough)
- Update history patterns
- Deprecated section patterns
- Redundant content patterns
- Pattern matching algorithms
- False positive handling
Load when: Detecting historical content or understanding pattern matching
For Usage Examples
See examples.md for:
- Basic conservative pruning
- Aggressive pruning
- Dry-run preview
- Pruning specific document
- Example pruning reports (before/after)
- Error scenarios (over-pruning, broken references)
Load when: User needs examples or clarification
Error Handling
No Historical Content Found
INFO: No historical content detected
Document: {doc}
All content appears current.
No pruning needed.
Over-Pruning Warning
WARNING: Pruning would remove >50% of content
Document: {doc}
Removal: {percentage}%
Suggestion: Review document - consider if it should be archived entirely
or switch to conservative mode.
Broken References After Pruning
ERROR: Pruning would break cross-references
Section: {section}
Referenced by: {other-docs}
Action: Preserved section to maintain references.
Update referencing docs before pruning.
Integration
Works well with:
/design-docs:design-sync - Sync docs before pruning to ensure currency/design-docs:design-review - Identify documents needing pruning/design-docs:design-validate - Validate after pruning/design-docs:design-archive - Archive documents that are mostly historical
Success Criteria
A successful pruning:
- ✅ Historical content identified accurately
- ✅ Staleness scores calculated
- ✅ Appropriate pruning strategy applied
- ✅ Cross-references preserved
- ✅ Document still validates
- ✅ Frontmatter updated with pruning metadata
- ✅ Clear pruning report generated
- ✅ Content reduction documented
