rag-from-scratch/.claude/commands/prepare-md.md

description, allowed-tools, argument-hint

description	allowed-tools	argument-hint
Legge un file Markdown, individua tutti i problemi che compromettono il chunking (artefatti, sillabazione, header malformati, paragrafi spezzati, gerarchia incoerente, sezioni vuote) e applica le correzioni direttamente sul file senza chiedere conferma per i casi chiari.	Read Bash Grep Edit	<path/to/clean.md oppure stem>

Risolvi il percorso del file da preparare:

!`python3 -c " import sys, json, re from pathlib import Path

arg = '$ARGUMENTS'.strip() root = Path('.')

candidates = [ Path(arg), root / arg, root / 'conversione' / arg / 'clean.md', root / 'step-4' / arg / 'clean.md', ]

md_path = None for p in candidates: if p.exists() and p.suffix == '.md': md_path = p break

if not md_path: print('ERRORE: file non trovato per:', arg) sys.exit(1)

print('MD_PATH=' + str(md_path))

Cerca profilo strutturale (report.json o structure_profile.json)

stem = md_path.parent.name profile_candidates = [ md_path.parent / 'report.json', md_path.parent / 'structure_profile.json', root / 'step-4' / stem / 'structure_profile.json', root / 'conversione' / stem / 'report.json', ] for sp in profile_candidates: if sp.exists(): try: d = json.load(open(sp)) st = d.get('structure', d) print(f'STRATEGIA={st.get("strategia_chunking","?")}') print(f'LINGUA={st.get("lingua_rilevata","?")}') print(f'H1={st.get("n_h1",0)} H2={st.get("n_h2",0)} H3={st.get("n_h3",0)}') for a in st.get('avvertenze', []): print(f'AVVISO: {a}') except Exception: pass break

Statistiche file

text = md_path.read_text(encoding='utf-8') lines = text.split('\n') pua = len(re.findall(r'[\ue000-\uf8ff]', text)) print(f'RIGHE={len(lines)} CHARS={len(text)}') if pua: print(f'PUA_RESIDUI={pua}') " 2>/dev/null`

Se l'output contiene ERRORE, comunica il percorso non trovato e fermati.

---

Leggi il file completo identificato da MD_PATH nell'output sopra. Poi esegui tutti i controlli e applica le correzioni nell'ordine indicato.

I parametri di riferimento per il chunking sono: MIN_CHARS=200, MAX_CHARS=800.

---

Controllo 1 — Sillabazione residua

Cerca blocchi di testo (non header) dove una riga termina con - e la successiva inizia con lettera minuscola: è un'interruzione di parola non risolta da PDF.

Esempio da correggere:

...il meccanismo di decen-
tralizzazione permette...

→ ...il meccanismo di decentralizzazione permette...

Applica ogni fusione con Edit. Se la parola ricomposta sembra errata, segnala invece di correggere.

---

Controllo 2 — Artefatti di pagina

Righe standalone che sono esclusivamente:

• Un numero intero isolato (numero di pagina)
• Titolo del libro / nome autore che si ripete identico 3+ volte nel documento
• Intestazioni di capitolo che si ripetono (es. ## 3. Termodinamica appare sia come header legittimo che come riga di testo duplicata)

Applica la rimozione con Edit per le ripetizioni chiaramente decorative. Segnala i casi ambigui.

---

Controllo 3 — Numeri di pagina in header

Header che terminano con | N o N dove N è un numero isolato (residuo di indice non rimosso):

• ### 16. Link vari | 109 → ### 16. Link vari
• ## Capitolo 3 42 → ## Capitolo 3

Applica con Edit.

---

Controllo 4 — Header malformati

Per ogni header (#, ##, ###):

a) ALL-CAPS non convertito: ## TERMODINAMICA DEI PROCESSI → ## Termodinamica dei processi Usa sentence case (prima lettera maiuscola, resto minuscolo salvo nomi propri evidenti). Applica.

b) Livello h4/h5/h6: #### Sottosezione → ### Sottosezione Applica.

c) Testo troppo lungo (> 120 char): Probabilmente non è un header ma testo estratto erroneamente. Rimuovi i # iniziali lasciando il testo come paragrafo normale. Applica se chiaramente non è un titolo. Segnala se ambiguo.

d) Header duplicati: Se lo stesso header appare due volte, rimuovi la seconda occorrenza (o la prima se è quella fuori contesto). Applica.

---

Controllo 5 — Paragrafi spezzati

Blocchi di testo (non header, non liste) che terminano senza punteggiatura finale (.?!»)).

Se il blocco successivo non inizia con lettera maiuscola e non è un header/lista, i due blocchi sono parte della stessa frase spezzata da un salto pagina PDF.

Applica la fusione solo quando sei certo (la congiunzione è evidente: inizia con congiunzione, continua la frase in modo inequivocabile). Segnala i casi dubbi invece di correggere.

---

Controllo 6 — Sezioni quasi-vuote o vuote

Sezione (header + corpo) con corpo < 100 caratteri:

• Se il contenuto è evidentemente una sottosezione o introduzione di ciò che segue (e non ha senso da solo), rimuovi l'header e unisci il testo alla sezione precedente o successiva.
• Se è un header di capitolo che introduce legittime sottosezioni (## seguito da ###), lascia invariato.

Applica le fusioni sicure. Segnala quelle ambigue.

---

Controllo 7 — Gerarchia heading

Verifica che la gerarchia sia coerente. Problemi da correggere:

• Più di un # (h1) nel documento → il secondo e successivi diventano ## salvo che siano chiaramente titoli di parti distinte
• ### prima del primo ## → abbassa il ### a ## o aggiungi un ## genitore appropriato
• ## prima del primo # in documenti con h1 → lascia invariato (alcuni documenti non hanno h1)

Applica solo le correzioni di livello sicure. Segnala le ristrutturazioni che richiedono giudizio.

---

Controllo 8 — Sezioni troppo lunghe senza struttura

Sezione (## o ###) con corpo > 3000 caratteri e nessun header figlio al suo interno: il chunker la spezzerà su frasi in modo meccanico, perdendo coerenza semantica.

Se il testo contiene chiari cambio-argomento (paragrafi separati da riga vuota, con transizioni come "Inoltre...", "In secondo luogo...", "Un altro aspetto..."), considera di aggiungere un ### per suddividere semanticamente.

Non aggiungere header inventati. Segnala le sezioni candidate e proponi i titoli: applica solo su risposta affermativa.

---

Report finale

Dopo aver applicato tutte le correzioni automatiche, mostra:

File: <path>
Correzioni applicate: N totali

  Sillabazione risolta:       N
  Artefatti pagina rimossi:   N
  Numeri pagina in header:    N
  Header normalizzati:        N (ALL-CAPS, livello, lunghezza, duplicati)
  Paragrafi fusi:             N
  Sezioni quasi-vuote risolte:N
  Gerarchia corretta:         N

Problemi aperti (richiedono giudizio manuale):
  [riga N] <descrizione precisa>
  ...

Se non ci sono problemi aperti: "Markdown pronto per il chunking." Se ci sono problemi aperti: elencali e chiedi quali applicare.