rag-from-scratch/.claude/commands/post-chunk.md

description, allowed-tools, argument-hint

description	allowed-tools	argument-hint
Perfeziona i chunk di un documento (verifica, dry-run, fix, ri-verifica) e li prepara per la vettorizzazione.	Read Bash Grep	<stem>

Passo 0 — Verifica fresca

Esegui sempre verify_chunks.py per un report aggiornato:

source .venv/bin/activate && python chunks/verify_chunks.py --stem $ARGUMENTS

Leggi il report appena generato:

!python3 -c " import json, sys try: r = json.load(open('chunks/$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'), ('incomplete_math','Math incompleto')]: 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 bloccante. Comunica:

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

Se ci sono solo 🟡, spiega brevemente i warning e chiedi se l'utente vuole risolverli prima o procedere.

---

Se verdict == "warnings_only" o "blocked"

Passo 1 — Dry-run

source .venv/bin/activate && python chunks/fix_chunks.py --stem $ARGUMENTS --dry-run

Spiega in italiano ogni operazione pianificata:

• rimuovi chunk vuoti — privi di testo, non contribuiscono al retrieval
• aggiungi prefisso — [sezione > titolo] fornisce contesto all'embedding; senza, il chunk è decontestualizzato
• fondi incompleti — frase spezzata a metà: il chunk corrente e il successivo formano una frase unica
• fondi troppo corti — sotto MIN_CHARS: troppo brevi per portare informazione semantica utile
• spezza troppo lunghi — 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

source .venv/bin/activate && python chunks/fix_chunks.py --stem $ARGUMENTS

Passo 4 — Ri-verifica automatica

source .venv/bin/activate && python chunks/verify_chunks.py --stem $ARGUMENTS

Leggi il nuovo chunks/$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 chunks/$ARGUMENTS/chunks.json
   Procedi con la vettorizzazione:
   python step-8/ingest.py --stem $ARGUMENTS

Se rimangono 🔴 dopo il fix (testo non spezzabile o struttura anomala nel sorgente):

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