title: "How We Cleaned Up 9,000+ Lines of Dead Documentation (And Built a System to Keep It Clean)" description: "Documentation rot is inevitable. We deleted 47 obsolete files, reorganized 84+ docs, and built an automated lifecycle system to prevent future chaos." published: 2025-12-30 author: Alexey Anshakov tags: [documentation, devops, technical-debt, build-in-public]

How We Cleaned Up 9,000+ Lines of Dead Documentation (And Built a System to Keep It Clean)

TL;DR

  • Problem: 84 .md files scattered across /docs, 47 obsolete migration reports, zero structure.
  • Solution: Reorganized into tasks/, guides/, strategies/, rules/ with automated lifecycle tracking.
  • Result: Deleted 9,295 lines of dead docs, created a self-cleaning system with 30/90-day retention rules.
  • Key Insight: Documentation needs garbage collection, not just creation.

The Problem: Death by a Thousand Markdown Files

Let me paint a picture: You're 6 months into a project. You've shipped features, fixed bugs, refactored code. And every single one of those events left behind a .md file:

  • PHASE3_1_COMPLETE.md (what was Phase 3?)
  • SONAR_PINGS_INFINITE_LOOP_FIX.md (still relevant?)
  • TiptapEditor_Migration.md (already deployed?)

Your /docs folder now has 84 files. Some are critical (DATABASE_ARCHITECTURE.md). Most are temporary trash.

The Real Cost

This isn't just clutter. It's cognitive overhead:

  1. Onboarding friction: New devs open /docs and see 50 files. Where do they start?
  2. Outdated info: You read BACKEND_MIGRATION.md (7 months old). Is this still the plan?
  3. Lost knowledge: Buried under junk is ENV_VARIABLES.md — actually critical.

We needed documentation garbage collection.

The Audit: What Got Deleted

I ran a full audit of all 84 .md files. Here's what I found:

Category 1: Completed Migrations (18 files → Archived)

PHASE0_COMPLETE.md
PHASE1_COMPLETE.md
LOGGER_STANDARDIZATION_COMPLETE.md
VISUAL_DEBUGGER_IMPLEMENTATION.md
...

Why delete? These are historical records, not living docs. Value = zero after 90 days.

Action: Moved to /archived. Auto-delete in 90 days.

Category 2: Duplicate/Obsolete Strategy (7 files → Archived)

LMO_UPDATES.md (duplicate of LMO_STRATEGY.md)
TODO_SDK.md (merged into main TODO.md)
SEO-BLOG-READY.md (outdated, blog already launched)

Why delete? Either duplicates or snapshots of things that evolved.

Action: Archived. Kept latest version only.

Category 3: Temporary Junk (5 files → Deleted)

example.jpeg (random test image)
implementation-summaries/2025-12-19-createpingmodal-fix.md
docs/description/# Perplexity Prompt...md

Why delete? Zero long-term value.

Action: Straight to /dev/null.

The System: Documentation Lifecycle Rules

Deleting files is easy. Keeping them deleted is hard.

We created a lifecycle system inspired by cloud storage (S3 Lifecycle Policies):

Folder Structure

docs/
├── rules/              # ⚖️ Permanent (never delete)
├── guides/             # 📚 Permanent (rarely change)
├── strategies/         # 🎯 Permanent (living docs)
├── specs/              # 📘 Permanent (BDD specs)
├── tasks/
│   ├── active/         # 🔥 Current work
│   └── completed/      # ✅ Auto-delete after 30 days
└── archived/           # 📦 Auto-delete after 90 days

Lifecycle Rules

Type Location Retention Auto-Delete
Permanent Docs rules/, guides/, strategies/ Forever ❌
Active Tasks tasks/active/ Until done ❌
Completed Tasks tasks/completed/ 30 days ✅
Historical Reports archived/ 90 days ✅

Task Document Frontmatter

Every temporary doc must have metadata:

---
type: task
status: active | completed
created: 2025-12-30
completed: null | 2025-12-31
priority: high | medium | low
tags: [migration, database]
---

# Task Name

## ✅ Checklist

- [ ] Step 1
- [ ] Step 2
- [x] Step 3 (done)

This enables automation.

The Automation: Weekly Cleanup Script

We don't trust humans to delete old files. Here's the cron job:

#!/bin/bash
# Run every Monday at 9 AM

# Move completed tasks (>30 days) to archived
find docs/tasks/completed -name "*.md" -mtime +30 -exec mv {} docs/archived/ \;

# Delete archived files (>90 days)
find docs/archived -name "*.md" -mtime +90 -delete

# Log stats
echo "📊 Docs Statistics:"
echo "  Active tasks: $(ls docs/tasks/active | wc -l)"
echo "  Completed: $(ls docs/tasks/completed | wc -l)"
echo "  Archived: $(ls docs/archived | wc -l)"

Why this works:

  • No manual decisions: Files age out automatically.
  • Safety net: 30-day buffer in completed/ before archiving.
  • Auditability: All deletes logged.

The Results: Before & After

Before

docs/
├── PHASE0_COMPLETE.md
├── PHASE1_COMPLETE.md
├── BACKEND_MIGRATION.md
├── LMO_UPDATES.md
├── LMO_STRATEGY.md
├── ENV_VARIABLES.md
├── TODO_SDK.md
├── example.jpeg
├── migration/
│   ├── SONAR_PINGS_FIX.md
│   ├── BDD_MIGRATION_PLAN.md (active!)
│   └── DATABASE_CLEANUP_REPORT.md (done!)
└── ... 76 more files

Problem: Zero signal-to-noise. Critical docs buried.

After

docs/
├── rules/              # 5 files (commits, d1, r2, versioning, markdown-docs)
├── guides/             # 5 files (env, ga4, ports, scripts, observability)
├── strategies/         # 4 files (lmo, seo, ai-citation, unit-economics)
├── tasks/active/       # 4 files (BDD_MIGRATION_PLAN, E2E_TESTS, ...)
├── tasks/completed/    # 3 files (auto-delete in 30 days)
├── specs/              # 44 files (BDD format)
└── archived/           # 26 files (auto-delete in 90 days)

Result: Crystal clear hierarchy. Every file has a purpose and expiration date.

Lessons Learned

1. Documentation is Code — It Needs Refactoring

You wouldn't leave dead code in main for 6 months. Why accept dead docs?

2. Lifecycle > Organization

Folders alone don't solve the problem. You need expiration dates.

3. Automate or Die

Manual cleanup never happens. Cron jobs are your friend.

4. Task Documents ≠ Specs

Temporary task docs (DATABASE_CLEANUP_PLAN.md) should auto-delete. Specs (FeedPlatform.md) should live forever.

What's Next?

We're adding:

  1. GitHub Action: Auto-cleanup on CI instead of cron.
  2. Pre-commit hook: Reject task docs without frontmatter.
  3. Analytics: Track which docs are never opened (candidates for deletion).

FAQ

Q: What if I need an old migration report?

A: Check archived/ (90-day retention). After that, it's in Git history.

Q: What about BizCom (old)/?

A: Historical archive. Never touched, never deleted. It's a museum.

Q: Won't this delete important info?

A: Only temporary task docs auto-delete. Permanent docs (rules/, guides/, specs/) stay forever.

Q: How do you decide what's "permanent"?

A: If it's referenced in active code or onboarding, it's permanent. If it's a status update, it's temporary.

Open Source This

Key files:

  • Rule: docs/rules/markdown-docs.md (lifecycle system)
  • Audit: docs/tasks/completed/DOCS_AUDIT_2025-12-30.md (full breakdown)
  • Commits: 671a706, 4448062