refactor(skills): rinomina step6-fix → post-chunk

- rimpiazza .claude/commands/step6-fix.md con post-chunk.md - aggiorna path da step-6/ a chunks/ in tutta la skill - aggiunge gestione incomplete_math nel report summary - scope ampliato: workflow completo fino alla vettorizzazione - CLAUDE.md: aggiorna /step6-fix → /post-chunk
2026-04-20 14:25:18 +02:00
parent f340c4c14e
commit 16029f1ef2
2 changed files with 24 additions and 25 deletions
@@ -0,0 +1,119 @@
+---
+description: Perfeziona i chunk di un documento (verifica, dry-run, fix, ri-verifica) e li prepara per la vettorizzazione.
+allowed-tools: Read Bash Grep
+argument-hint: <stem>
+---
+
+## Passo 0 — Verifica fresca
+
+Esegui sempre `verify_chunks.py` per un report aggiornato:
+
+```bash
+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
+
+```bash
+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
+
+```bash
+source .venv/bin/activate && python chunks/fix_chunks.py --stem $ARGUMENTS
+```
+
+### Passo 4 — Ri-verifica automatica
+
+```bash
+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
+```