Progressive Disclosure for Documentation

Rule

Restructure large documentation files (>500 lines, >5k tokens) into slim indexes with on-demand detail directories.

Context

When always-included documentation files consume excessive context tokens.

Detection

Observable signals:

• Documentation file > 500 lines always included
• Context budget consumed by rarely-needed content
• Single file contains 10+ distinct sections
• Agent frequently loads details never used

Pattern

Split monolithic docs into slim index + detail directories:

# Before: monolithic (11k tokens always)
TOOLS.md
├── Section 1 (rarely needed)
├── Section 2 (rarely needed)
└── ... (15+ sections)

# After: progressive (4k tokens always)
tools/
├── README.md     # Slim index with links
├── topic1/       # On-demand (~1k each)
├── topic2/
└── .../

Slim index structure:

• Brief overview (2-3 paragraphs)
• Quick reference table (common operations)
• Navigation links to detail directories
• Core principles (bullet list)

Outcome

Following this pattern results in:

• 40-60% token reduction in always-included context
• Faster responses (less to process)
• On-demand loading (details when needed)
• Better maintainability (smaller files)

Related

• Progressive Disclosure Skill - Full implementation guide
• Issue #49 - Original proposal