We deleted 9,000+ lines of dead documentation and built an automated cleanup system

tl;dr: Built a system that auto-deletes temporary documentation based on retention policies (30/90 days). Deleted 47 obsolete files, zero regrets.

Pretty standard situation: yuo ship features, fix bugs, refactor code. Every event leaves a markdown file.


6 months later: 84 files in /docs. Most are useless.


The real problem isn't clutter. It's cognitive overhead:


1. New devs see 50 files, don't know where to start
2. You read BACKEND_MIGRATION.md - is this still the plan?
3. Critical info (ENV_VARIABLES.md) buried under junk


We needed documentation garbage collection.


The System:


Inspired by S3 lifecycle policies, we created folders with auto-delete rules:


```
docs/
├── rules/          # ⚖️ Permanent
├── guides/         # 📚 Permanent
├── strategies/     # 🎯 Permanent
├── tasks/active/   # 🔥 Current work
├── tasks/completed/ # ✅ Delete after 30 days
└── archived/       # 📦 Delete after 90 days
```


Every temporary doc has frontmatter:


```yaml
---
type: task
status: completed
created: 2025-12-01
completed: 2025-12-15
---
```


Weekly cron job:


```bash
# Move completed (>30d) → archived
find docs/tasks/completed -mtime +30 -exec mv {} docs/archived/ \;


# Delete archived (>90d)
find docs/archived -mtime +90 -delete
```


Results:
- 47 files deleted
- 26 archived (will auto-delete in 90d)
- 17 permanent docs
- Zero manual decisions


Key insight:
 Documentation is code. It needs refactoring AND deletion.


What do you think? How do you manage doc lifecycle?