rag-from-scratch/.claude/commands/step6-fix.md

---
description: Verifica i chunk di step 5, mostra i problemi, propone e applica le fix tramite fix_chunks.py con ri-verifica automatica finale.
allowed-tools: Read Bash Grep
argument-hint: <stem>
---

## Passo 0 — Verifica fresca (sempre)

Esegui sempre `verify_chunks.py` per avere un report aggiornato (non fidarti di un report.json preesistente):

```bash
source .venv/bin/activate && python step-6/verify_chunks.py --stem $ARGUMENTS
```

---

Leggi il report appena generato:

!`python3 -c "
import json, sys
try:
    r = json.load(open('step-6/$ARGUMENTS/report.json'))
    v = r.get('verdict','?')
    s = r.get('stats', {})
    t = r.get('thresholds', {})
    print(f'Verdict: {v}')
    print(f'Totale chunk: {s.get(\"total\",\"?\")}  |  OK: {s.get(\"ok\",\"?\")}')
    print(f'Min: {s.get(\"min_chars\",\"?\")} char  Max: {s.get(\"max_chars\",\"?\")} char  Media: {s.get(\"avg_chars\",\"?\")} char')
    print(f'Soglie: MIN={t.get(\"min_chars\",200)}  MAX={t.get(\"max_chars\",800)}')
    bl = r.get('blockers', {})
    wa = r.get('warnings', {})
    for cat, label in [('empty','Vuoti'), ('no_prefix','Senza prefisso'), ('incomplete','Frasi spezzate')]:
        items = bl.get(cat, [])
        if items:
            print(f'  🔴 {label}: {len(items)}')
            for c in items[:3]:
                print(f'     [{c[\"chunk_id\"]}] {c[\"n_chars\"]} char → {c[\"last_text\"][-60:]!r}')
    for cat, label in [('too_short','Troppo corti'), ('too_long','Troppo lunghi')]:
        items = wa.get(cat, [])
        if items:
            print(f'  🟡 {label}: {len(items)}')
            for c in items[:3]:
                print(f'     [{c[\"chunk_id\"]}] {c[\"n_chars\"]} char')
except Exception as e: print(f'ERRORE lettura report: {e}')
" 2>/dev/null`

---

## Se verdict == "ok"

✅ Nessun problema. Comunica:

```
✅ Chunk puliti — procedi con la vettorizzazione:
   python step-8/ingest.py --stem $ARGUMENTS
```

Fermati qui. Non eseguire nessun altro passo.

---

## Se verdict == "warnings_only" o "blocked"

### Passo 1 — Dry-run

```bash
source .venv/bin/activate && python step-6/fix_chunks.py --stem $ARGUMENTS --dry-run
```

Spiega in italiano ogni operazione pianificata:
- **rimuovi chunk vuoti** — chunk privi di testo, non contribuiscono al retrieval
- **aggiungi prefisso** — il prefisso `[sezione > titolo]` fornisce contesto all'embedding; senza, il chunk è semanticamente decontestualizzato
- **fondi incompleti** — frase spezzata a metà: il chunk corrente e il successivo formano una frase unica
- **fondi troppo corti** — chunk sotto MIN_CHARS: troppo brevi per portare informazione semantica utile
- **spezza troppo lunghi** — chunk sopra MAX_CHARS×1.5: troppo densi, degradano la precision del retrieval

Se ci sono solo 🟡 (nessun 🔴), informa che si può procedere anche senza fix e chiedi la preferenza.

### Passo 2 — Conferma

Chiedi: **"Applico le correzioni?"**

Applica solo su risposta affermativa esplicita.

### Passo 3 — Applica

```bash
source .venv/bin/activate && python step-6/fix_chunks.py --stem $ARGUMENTS
```

### Passo 4 — Ri-verifica automatica

```bash
source .venv/bin/activate && python step-6/verify_chunks.py --stem $ARGUMENTS
```

Leggi il nuovo `step-6/$ARGUMENTS/report.json` e riporta:
- Nuovo verdict
- Delta chunk (N prima → N dopo)
- Problemi residui se presenti

### Passo 5 — Conclusione

Se verdict finale è `ok` o `warnings_only` senza 🔴:

```
✅ Chunk pronti in step-6/$ARGUMENTS/chunks.json
   Procedi con la vettorizzazione:
   python step-8/ingest.py --stem $ARGUMENTS
```

Se rimangono 🔴 dopo il fix (raro — testo non spezzabile o struttura anomala):

```
🔴 X problemi residui non risolvibili automaticamente.
   Torna a step-4/$ARGUMENTS/clean.md e correggi manualmente le sezioni indicate,
   poi riesegui nell'ordine:
     python step-5/chunker.py --stem $ARGUMENTS --force
     python step-6/verify_chunks.py --stem $ARGUMENTS
```