# 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
```