cc-os/plugins/cc-architect/references/progressive-disclosure/splitting-knowledge.md

Splitting Knowledge Docs

When to keep knowledge together vs. split it apart.

The core question

"Will these pieces of knowledge always be needed together, or are there times you need one but not the other?"

If always together → keep in one file. If sometimes separate → split into multiple files.

Size guidelines

• Target: under 150 lines per knowledge doc
• Hard limit: 200 lines (split if approaching this)
• reference.md files: under 50 lines

Signs you should split

• The doc covers multiple distinct concepts
• You find yourself scrolling past irrelevant sections
• Different workflows need different parts of the doc
• The doc has more than 3-4 top-level sections

Signs you should NOT split

• The concepts are tightly coupled (understanding A requires B)
• The doc is under 100 lines and cohesive
• Splitting would create files under 30 lines (too granular)

How to split

1. Identify the natural boundaries (usually top-level headings)
2. Create a subdirectory if splitting creates 3+ files
3. Move content to new files
4. Update the parent reference.md to describe the new structure
5. Add a reference.md to any new subdirectory

Depth limits

• Maximum recommended depth: 3 levels (references/topic/subtopic/)
• If you need deeper, consider whether this belongs in a separate skill

Example split

Before:

references/
└── api-design.md  (250 lines covering auth, pagination, errors)

After:

references/
└── api-design/
    ├── reference.md
    ├── authentication.md
    ├── pagination.md
    └── error-handling.md