rag-from-scratch/.claude/commands/step4-review.md

---
description: Revisione qualitativa del clean.md dopo il pre-processing automatico (step 4). Trova artefatti residui, paragrafi spezzati e header errati, poi propone le correzioni.
allowed-tools: Read Bash Grep Edit
argument-hint: <stem>
---

Esegui la revisione qualitativa di `step-4/$ARGUMENTS/clean.md`.

**Cosa è già stato fatto automaticamente (revision_log):**
!`grep -A 12 "^## $ARGUMENTS" step-4/revision_log.md 2>/dev/null || echo "(nessun log trovato per questo stem)"`

**Profilo strutturale attuale:**
!`python3 -c "
import json, sys
try:
    d = json.load(open('step-4/$ARGUMENTS/structure_profile.json'))
    print(f'Livello: {d[\"livello_struttura\"]}  Strategia: {d[\"strategia_chunking\"]}')
    print(f'h1={d[\"n_h1\"]}  h2={d[\"n_h2\"]}  h3={d[\"n_h3\"]}  paragrafi={d[\"n_paragrafi\"]}')
    print(f'Lunghezza media sezione: {d[\"lunghezza_media_sezione\"]} char')
    for a in d.get('avvertenze', []): print(f'  ⚠️  {a}')
except Exception as e: print(f'ERRORE: {e}')
" 2>/dev/null`

---

Analizza `step-4/$ARGUMENTS/clean.md` eseguendo i grep seguenti e ragionando sui risultati. Per ogni check: esegui il grep, conta i risultati, riporta i casi concreti (max 5 esempi con numero di riga).

## Check 1 — Sillabazione residua

Righe che terminano con trattino seguito da testo nella riga successiva (artefatto PDF non risolto):

```bash
grep -n "\-$" step-4/$ARGUMENTS/clean.md | head -20
```

Segnala se presenti: numero di riga, testo della riga e della riga successiva.

## Check 2 — Righe orfane (artefatti PDF)

Righe standalone (non header `#`, non vuote) di meno di 60 caratteri che sembrano artefatti:

```bash
grep -n "^[^#\-\*\|].\{1,59\}$" step-4/$ARGUMENTS/clean.md | grep -v "^\s*$" | head -30
```

Valuta ogni riga: è testo normale breve (legittimo) o artefatto (numero di pagina, nome autore isolato, riga di intestazione ripetuta)?

## Check 3 — Paragrafi con frase spezzata

Blocchi di testo che terminano senza punteggiatura di fine frase (`.?!»)`):

```bash
grep -n "[^.!?»)\]\'\"]$" step-4/$ARGUMENTS/clean.md | grep -v "^[0-9]*:#" | grep -v "^[0-9]*:\s*$" | grep -v "^\s*[-\*]" | head -20
```

Riporta i casi più sospetti (righe brevi che finiscono a metà concetto).

## Check 4 — Header sospetti

```bash
grep -n "^##\? " step-4/$ARGUMENTS/clean.md | head -40
```

Verifica:
- `##` o `###` con contenuto interamente MAIUSCOLO non convertito → segnala
- Header duplicati (stesso testo che appare due volte) → segnala
- `##` con testo > 80 caratteri (probabile testo che non è un header) → segnala
- Salti di livello anomali (es. `###` senza un `##` padre) → segnala

## Check 5 — Sezioni quasi vuote

```bash
python3 -c "
import re, sys
text = open('step-4/$ARGUMENTS/clean.md').read()
sections = re.split(r'^(#{1,3} .+)$', text, flags=re.MULTILINE)
for i in range(1, len(sections)-1, 2):
    header = sections[i].strip()
    body = sections[i+1].strip() if i+1 < len(sections) else ''
    if len(body) < 80 and body:
        print(f'{header!r} → {len(body)} char: {body[:60]!r}')
    elif not body:
        print(f'{header!r} → VUOTA')
" 2>/dev/null | head -20
```

Sezioni con body < 80 char o vuote compromettono il chunking. Segnala quelle che non hanno senso come sezione autonoma.

## Check 6 — Gerarchia strutturale

```bash
grep -n "^#\{1,3\} " step-4/$ARGUMENTS/clean.md | head -50
```

Verifica che la gerarchia sia coerente: `# → ## → ###`. Segnala se ci sono `###` prima del primo `##`, o `##` prima del primo `#`, o `#` multipli (più di un h1).

---

## Report finale

```
🔴 BLOCCANTI (compromettono il chunking o il retrieval)
  [riga N] descrizione precisa del problema
  ...

🟡 MINORI (artefatti visibili, non bloccanti)
  [riga N] descrizione
  ...

🟢 OK — nessun problema rilevato in questa categoria
```

Poi chiedi: **"Applico le correzioni per i 🔴? E per i 🟡?"**

Applica solo ciò che viene esplicitamente approvato. Usa Edit per ogni modifica — mai riscrivere l'intero file.