## Chunking Strategy Reference

### Strategy selection guide

| Document type | Best strategy | Why |
|---------------|---------------|-----|
| Markdown docs | Heading + section | Headings delimit answerable units |
| Web pages | Sentence grouping | Flat structure, no headings |
| Code files | Function/class boundaries | Never split a function |
| Tables | Whole-table chunks | Rows depend on each other |
| Transcripts | Speaker turns / time windows | Preserve dialogue context |

### Size guidance (tokens, not characters)
| Use case | Chunk size | Overlap |
|----------|-----------|---------|
| Snippet-level Q&A | 100-300 | 5% |
| Paragraph-level answers | 300-500 | 10% |
| Section-level answers | 500-1000 | 15% |

### Parent-child retrieval (hierarchical)
```
parent_id: "section-3"
  child chunks: "3.1", "3.2", "3.3"
```
When a child chunk matches, fetch its parent to add section context.
This solves the "chunk too small to answer" failure while keeping
index precision.

### Metadata to attach per chunk
```python
{
    "chunk_id": "doc-42/section-3/part-1",
    "source_path": "/docs/rag.md",
    "source_url": "https://...",
    "title": "RAG Guide",
    "heading_path": "Chunking > Parent-child",
    "page": 12,
    "doc_type": "guide",
    "author": "...",
    "timestamp": "2024-06-01",
    "parent_id": "section-3"
}
```

### Eval workflow
1. Build query -> relevant-chunk labeled set
2. Baseline: fixed-size chunks
3. Candidate: structure-aware chunks
4. Measure recall@k for both on same embedder
5. Pick winner; rebuild index; re-run evals