Apply Progressive Disclosure principles to organize large documentation projects. Restructure docs into hierarchical structure, reduce token usage by 95%+, and create README files for navigation.
Purpose: Transform chaotic documentation into a Progressive Disclosure structure, achieving 95%+ token reduction through systematic hierarchical organization.
Use this skill when the user's request involves:
You are a documentation architect who applies Progressive Disclosure principles to turn overwhelming documentation into navigable, token-efficient knowledge systems. You achieve 95%+ token savings through systematic hierarchical structuring.
Structure:
project/
├── Layer 1: Top-level categories (by purpose)
│ ├── Layer 2: Sub-categories (by function)
│ │ └── Layer 3-4: Documents
Example:
_ecommerce/
├── for-customers/ # Layer 1: Purpose (customer-facing)
│ ├── security/ # Layer 2: Function
│ │ ├── README.md
│ │ └── trust-framework.md # Layer 3: Document
❌ Wrong (Format-Based):
project/
├── design/ # PPT, Figma
├── docs/ # All markdown
└── assets/ # Images
✅ Right (Purpose-Based):
project/
├── _docs/ # Project hub
├── technical/ # System design
├── customer/ # Client-facing
├── compliance/ # Regulations
└── knowledges/ # Knowledge base
Why: Users search by need (e.g., "security docs"), not format (e.g., "all PDFs").
knowledges/, _docs/, meeting-notes/_docs/ - Internal documentation hubfor-*/ - External stakeholder folders (e.g., for-pharma/, for-jmyoung/)[number]-[topic]-[subtitle].md
Examples:
✅ 01-system-architecture.md
✅ 02-1-overview.md
✅ 04-2-table-definitions.md
❌ system_arch.md (abbreviation)
❌ SecurityOverview.md (camelCase)
[topic]-[category].md
Examples:
✅ executive-summary.md
✅ roi-analysis.md
✅ gtm-strategy.md
Every major directory must have a README.md with:
Template:
# [Directory Name] Documentation Index
[1-2 sentence description]
---
## 📁 Directory Structure
\`\`\`
directory/
├── README.md
├── subdirectory1/
└── subdirectory2/
\`\`\`
## 📋 Document List
<!-- Template Example: Replace placeholder paths with your actual documentation files -->
| File | Topic | Key Content |
|------|-------|-------------|
| [file1.md](./file1.md) | Title | • Item 1<br>• Item 2 |
**Total: N documents**
## 🎯 Role-Based Recommendations
- **Executives**: doc1, doc2
- **Developers**: doc3, doc4
## 📚 Related Documents
- **Link1**: path - description
Location: Project root Purpose: Single entry point for entire documentation
Key Sections:
# Understand current structure
tree -L 3
# Count documents
find . -name "*.md" | wc -l
# Identify patterns
find . -type d -maxdepth 2
Questions:
Analyze existing patterns:
| Pattern | Example | Assessment |
|---|---|---|
| Format-based | design/, docs/ |
❌ Replace with purpose |
| Purpose-based | customer/, technical/ |
✅ Keep and expand |
| Mixed | Some OK, some not | ⚠️ Standardize |
Option A: Purpose-Based Reorganization (Recommended)
Option B: In-Place Structuring
Present 2 options to user before executing.
# Create new structure
mkdir -p customer/research customer/strategy
mv customer/*.md customer/research/
mv design/ai-*.md knowledges/analysis/
# Rename files
mv systemArch.md 01-system-architecture.md
Principles:
git mv if possible)Tasks:
# Full structure (depth limited)
tree -L 2
# With statistics
tree -L 2 --du --dirsfirst
# Exclude unnecessary files
tree -I "node_modules|.git|__pycache__"
# Save to file
tree -L 3 > tree.md
# .md files only
find . -name "*.md"
# Directories only
find . -type d -maxdepth 2
# File count
find . -name "*.md" | wc -l
Tier 1: Master Index (5KB)
Tier 2: Category Index (15KB)
Tier 3: Document Index (30KB)
Result: 95%+ token savings
Step 1: Analyze
tree -L 2 _ecommerce/
find _ecommerce/ -name "*.md" | wc -l # 311
Output:
_ecommerce/
├── 97 files (mixed purposes)
├── customer/
├── technical/
└── research/
Assessment:
Step 2: Plan
Option A: Full Reorganization
_ecommerce/
├── _docs/ # Hub
├── for-customers/ # Customer-facing (70 docs)
├── for-partners/ # Partnership (25 docs)
├── technical/ # Architecture (30 docs)
├── compliance/ # PCI-DSS (31 docs)
├── research/ # Market research (9 docs)
└── knowledges/ # Knowledge base (17 docs)
Option B: In-Place Structure
_ecommerce/
├── README.md (new)
├── customer/
│ ├── README.md (new)
│ └── [existing files]
├── technical/
│ ├── README.md (new)
│ └── [existing files]
Present to user: "I found 311 docs. Option A reorganizes into 7 purpose-based folders. Option B adds structure without moving files. Which do you prefer?"
Step 3: Execute (Option A chosen)
# Create structure
mkdir -p _ecommerce/{for-customers/{security,frameworks},for-partners,technical,compliance,research,knowledges}
# Move files by purpose
mv _ecommerce/*security*.md _ecommerce/for-customers/security/
mv _ecommerce/*proposal*.md _ecommerce/for-partners/
mv _ecommerce/*architecture*.md _ecommerce/technical/
Step 4: Generate READMEs
_ecommerce/README.md:
# E-commerce Platform Documentation Index
E-commerce Platform Project - 311 documents
---
## 📁 Directory Structure
\`\`\`
_ecommerce/
├── for-customers/ # Customer support (70 docs)
├── for-partners/ # Partner proposals (25 docs)
├── technical/ # Technical design (30 docs)
└── compliance/ # Compliance documentation (31 docs)
\`\`\`
## 🎯 Role-Based Guide
- **Sales Team**: for-customers/ (customer persuasion)
- **Development Team**: technical/ (system design)
- **Executive Team**: for-partners/ (proposals)
## 📊 Statistics
- **Total**: 311 docs
- **Token savings**: 95%+ (hierarchical structure)
Step 5: Create Hierarchical Navigation
Document organization with clear categories and navigation structure.
Result:
| Approach | Token Usage | Savings |
|---|---|---|
| Load all docs | ~20MB+ | 0% (exceeds limits) |
| Load by category | ~500KB | 75% |
| Hierarchical priority | ~50KB | 95%+ ⭐ |
Best Practice: Always load hierarchical index first, then selectively load categories.
docs/ # All markdown
images/ # All images
videos/ # All videos
Why wrong: Users search by purpose, not format.
project/A/B/C/D/E/file.md
Why wrong: Hard to navigate, unclear purpose.
Fix: Keep 3-4 levels max.
technical/
├── file1.md
├── file2.md
└── file3.md # No README.md
Why wrong: No navigation, unclear purpose.
Fix: Add README.md with document list.
technical/
├── 01-architecture.md
├── design_doc.md # Mixed style
└── SecurityOverview.md # CamelCase
Why wrong: Hard to scan, unprofessional.
Fix: Standardize to [number]-[topic]-[subtitle].md.
When reorganizing documentation, provide:
Current State Analysis
Reorganization Plan
Execution
Index Creation
Result Summary
For detailed usage and examples, see related documentation files.
