# Line Count Targets — Dense Documentation Sizing

<!-- contamination-scan: skip — file is 100% illustrative sample-domain examples (fenced split-strategy snippets, bash commands); the docs/references/api/ literals are intentional teaching, not portable contamination. See the disclaimer blockquote below. -->

Soglie validate su 45 file riscritti. Obiettivo: mantenere chunks LightRAG gestibili e signal/noise alto.

> File path examples below (`docs/references/api/booking.md`, ecc.) are taken
> from a sample project (multi-merchant fidelity platform) and are kept as
> concrete illustrations. Sostituisci con le tue path effettive
> (`${paths.references_dir}/...`) e i tuoi domini. Le soglie numeriche e le
> regole di split valgono indipendentemente dal dominio.

## Target per doc type

| Doc type | Max linee | Sweet spot | Azione se supera |
|----------|-----------|------------|------------------|
| **API ref singolo** | 1500 | 400-900 | Split in sub-files per sub-domain |
| **PRD** | 1500 | 600-1200 | Split per capitoli/fasi |
| **UI ref** | 1500 | 500-1000 | Split per area applicativa |
| **Collections doc** | 1000 | 400-700 | Split per collection family |
| **ADR** | 200 | 60-150 | NON superare; se serve più, crea follow-up ADR |
| **Index/registry** | 500 | 100-300 | Solo pointer+summary, niente contenuto sostanziale |
| **Guide/runbook** | 800 | 200-500 | Split per workflow/fase |

## Motivazioni tecniche

### LightRAG chunking
- Chunk size: 100-6000 caratteri (~150-1000 token)
- File >1500 linee producono 30+ chunks → dilution semantic similarity
- Chunk boundary su heading boundaries → struttura gerarchica chiara aiuta

### Token budget per LLM entity extraction
- Ogni chunk × ~2-5 chiamate LLM (entity+relationship extraction)
- File gigante = molti chunk = costi esponenziali durante reindex
- File 1500 linee × 30 chunk × 3 LLM calls = 90 calls (gestibile)
- File 4000 linee × 80 chunk × 3 LLM calls = 240 calls (lento)

### Signal/noise
- File piccoli (<500 linee) hanno tipicamente S/N >80%
- File medi (500-1500) S/N 70-80%
- File grandi (>1500) S/N 50-65% — verbosità cumulativa
- Target generale: **>75% S/N ratio**

## Regola empirica scanning

Se un reviewer umano scorre velocemente il file:
- **<1500 linee**: può tenere il contesto in mente
- **1500-2500**: serve TOC o grep mirato
- **>2500**: si perde, va splittato

Stessa cosa per LLM context window utility.

## Quando splittare

### Criterio 1: linee supera soglia
File >1500 linee (reference/PRD/UI) → candidate per split.

### Criterio 2: multiple sub-domains
Un file `api/booking.md` che contiene:
- Rooms CRUD
- Tables CRUD
- Reservations
- Availability
- Tags
- ...

→ Split in `api/booking/rooms-tables-combos.md`, `api/booking/reservations.md`, etc.

### Criterio 3: differente audience
Se parte del file è per MERCHANT e parte per ADMIN → considerare split.

## Struttura post-split

### Option A: sub-folder + parent index

```
docs/references/api/booking.md           # parent/index, ~500 linee
docs/references/api/booking/
  ├── rooms-tables-combos.md              # detail
  ├── reservations.md                     # detail
  └── policies-availability.md            # detail
```

Parent `booking.md` ha solo: intro dominio + index per sub-files + endpoint shared (ping, health).

### Option B: sibling files

```
docs/references/api/booking-rooms.md
docs/references/api/booking-reservations.md
docs/references/api/booking-tags.md
```

Meno gerarchico, più semplice per navigazione.

## Anti-pattern

❌ **Split forzato** di file ben bilanciati (<1500 linee) solo per rispettare target.
❌ **Eliminare contenuto semantico** per rispettare target → preferire split.
❌ **Tabelle mega-width** (>8 colonne) — si comprimere orizzontalmente ma illeggibile.
❌ **Micro-file** (<100 linee) per ogni endpoint — overhead metadata + chunk sovrapposizione.

## Quick check durante scrittura

```bash
wc -l docs/references/api/my-new-file.md
```

- >1500 linee → pianifica split PRIMA di finire
- 1000-1500 → è al limite, verifica se c'è compressione possibile
- 400-900 → dimensione ottimale
- <300 → considera merge con file correlato se ha poco contenuto
