Aggiunge tesi-narrate, regola di completezza delle risposte e diagrammi del README piu leggibili

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.agents/skills/tesi-narrate/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: tesi-narrate
+description: Trasforma un argomento della tesi in un documento Markdown citato, in tre registri (briefing, spiegazione in linguaggio semplice, lezione progressiva), con elenco delle pagine usate e delle lacune. Usala per «spiegami…», «fammi un riassunto/briefing su…», «prepara una lezione su…» riguardo DPP, P3HT, PCL/ROP, bottle brush, ACQ, tecniche e risultati della tesi.
+---
+
+# tesi-narrate — briefing, spiegazione o lezione citati
+
+Sola lettura: restituisci il testo in chat e non scrivere file salvo richiesta esplicita. Italiano. Per il recupero segui i passi di **tesi-query** (indice, pagine intere, verifica su `raw/tesi.md`, difetti noti) e per le immagini **tesi-figure**.
+
+## Richiesta
+`<argomento> [registro]`, con registro `briefing` (predefinito), `plain-language` o `lecturer`. Se l'argomento manca, chiedilo. Se il registro non è uno dei tre, elencali e non procedere.
+
+## Procedura
+1. **Recupero.** Parti da `index.md`, `wiki/glossario.md`, `wiki/tesi.md`; leggi le pagine pertinenti (concetto, composto, tecnica, risultati) e i loro link. Escludi dalle fonti `index.md`, `log.md` e le pagine di sola navigazione.
+2. **Registro delle affermazioni** (prima di scrivere). Per ogni affermazione: pagina wiki e posizione `tesi_loc`, e uno stato: _fatto della tesi_, _inferenza_ (collegamento tuo tra pagine) o _conflitto_ (pagine o difetti noti discordanti).
+3. **Redazione.** Ogni frase fattuale ha accanto la citazione `[[pagina]]` con `(§, Tab./Fig., r.N)`. Dati copiati alla lettera. Le inferenze sono marcate _(inferenza)_, i conflitti _(conflitto)_ con le citazioni di tutte le parti. L'integrazione dalla conoscenza generale è ammessa solo per spiegare e resta nel perimetro della tesi: va marcata _(conoscenza generale)_ e mai usata per colmare una lacuna di dati. Se la tesi non riporta qualcosa, omettilo e nominalo in «Copertura».
+4. **Figure.** Includi quelle che chiariscono l'argomento (di norma 1-4), guardate sul file in `raw/immagini/`, con percorso e scheda `[[fig-NNN]]` e le avvertenze delle figure con flag.
+
+## Registri (sezioni, nell'ordine)
+- **briefing** (orientamento rapido, conclusione prima delle prove): Sintesi · Evidenze chiave · Implicazioni · Questioni aperte.
+- **plain-language** (per chi non conosce l'argomento; definisci i termini prima di usarli, frasi brevi, niente analogie che introducano fatti non citati): Che cosa significa · Idee chiave · Come si incastrano i pezzi · Cosa non sappiamo ancora.
+- **lecturer** (lezione progressiva dal contesto al meccanismo): Contesto · Concetti fondamentali · Come funziona · Implicazioni e limiti · Ricapitolazione.
+
+Il registro cambia stile e ordine, non il confine dei fatti.
+
+## Uscita
+1. Titolo con argomento e registro.
+2. Le sezioni del registro.
+3. `## Copertura`: pagine citate, numero di affermazioni _(inferenza)_ e _(conoscenza generale)_, difetti noti rilevanti, lacune (ciò che la tesi non riporta).
+
+Se non esistono pagine pertinenti, dillo e non produrre il documento. Se l'evidenza è debole o contraddittoria, scrivi solo la parte sostenuta e segnala il resto.

.agents/skills/tesi-query/SKILL.md

@@ -24,8 +24,11 @@ Se la domanda riguarda strutture, schemi, meccanismi, spettri, grafici o morfolo
 - Marca le aggiunte _(conoscenza generale)_ o in una sezione «Approfondimento»; le deduzioni _(inferenza)_. Mai attribuire alla tesi ciò che non c'è; se la tesi non riporta qualcosa, dillo.
 - Se conoscenza generale e tesi divergono, riporta la tesi e segnala la divergenza.
 
+## Profondità e completezza (priorità alta)
+Risposte **approfondite e complete**, non sintetiche (salvo richiesta esplicita di brevità). Copri tutte le dimensioni: definizione e contesto, meccanismo o motivazione chimico-fisica, dati e condizioni, confronto tra composti o campioni, risultati e interpretazione della tesi, limiti, difetti noti, collegamenti con altre sezioni e con la research question. Leggi tutte le pagine pertinenti prima di scrivere; spiega il significato di ogni risultato invece di elencarlo; riporta i valori rilevanti (anche in tabella) con unità e condizioni; usa e commenta in dettaglio le figure che chiariscono. Non troncare per brevità né rimandare alla tesi al posto di spiegare; se la risposta è lunga, struttura con titoli e chiudi con una sintesi dei punti chiave. Ciò che la tesi non riporta resta dichiarato come lacuna.
+
 ## Forma
-Risposta diretta in 2-4 righe, poi sviluppo con titoli brevi: concetto → dati/risultati → meccanismo → collegamenti con altre parti → limiti e avvertenze. Tabelle per confronti, LaTeX per le formule. Chiudi con «Per approfondire» (pagine `[[...]]`).
+Apri con una risposta diretta in 2-4 righe, poi sviluppa in modo esteso con titoli brevi: concetto → dati/risultati → meccanismo → collegamenti con altre parti → limiti e avvertenze. Tabelle per confronti, LaTeX per le formule. Chiudi con «Per approfondire» (pagine `[[...]]`).
 
 ## Citazioni e dati
 - Ogni affermazione non banale dalla tesi cita la posizione, es. `(§4.2, Tab. 14, r.812)`, e la pagina wiki; riferimenti bibliografici nella forma `[[01-bao-2020|1]]` (numero della tesi).

AGENTS.md

@@ -2,4 +2,4 @@
 
 Questo repo è una LLM-wiki in **sola lettura** sulla tesi «Sintesi e caratterizzazione di copolimeri bottle brush foto-elettro attivi». Leggi `CLAUDE.md` alla radice: contiene lo schema completo di consultazione (retrieval dalla wiki e dalle figure, integrazione con conoscenza generale entro il perimetro della tesi, citazioni, difetti noti). Non modificare `wiki/`, `raw/`, `index.md`, `log.md` salvo richiesta esplicita. Rispondi in italiano.
 
-Skill in `.agents/skills/`: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle), `tesi-fonti` (bibliografia).
+Skill in `.agents/skills/`: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle), `tesi-fonti` (bibliografia), `tesi-narrate` (briefing, spiegazione o lezione citati).

CLAUDE.md

@@ -64,6 +64,16 @@ Dopo il retrieval, costruisci la risposta più **articolata e completa** possibi
 - Se la conoscenza generale e la tesi divergono, riporta la tesi, segnala la divergenza e non correggerla in silenzio.
 - Se la wiki e `raw/tesi.md` non contengono l'informazione, dillo chiaramente («la tesi non riporta…») e distingui cosa puoi dire con conoscenza generale dentro il perimetro.
 
+## Profondità e completezza (priorità alta)
+Le risposte devono essere **approfondite e complete**, non sintetiche. Salvo che l'utente chieda esplicitamente una risposta breve, adotta per default la forma estesa:
+- **Copri tutte le dimensioni della domanda:** definizione e contesto, meccanismo o motivazione chimico-fisica, dati e condizioni sperimentali, confronto tra composti o campioni, risultati e interpretazione data dalla tesi, limiti, difetti noti, collegamenti con altre sezioni e con la research question (ACQ, integrità elettrochimica del core DPP).
+- **Recupero ampio prima di scrivere:** leggi tutte le pagine pertinenti (concetto, composto, tecnica, risultati, analisi dei difetti), non fermarti alla prima che risponde. Nel dubbio se una pagina serva, leggila.
+- **Spiega, non elencare:** per ogni risultato dì cosa significa e perché, usando la conoscenza generale (marcata) per rendere comprensibili meccanismi, definizioni e ordini di grandezza, sempre dentro il perimetro della tesi.
+- **Dati completi:** riporta i valori rilevanti (anche in tabella) con unità e condizioni, non solo la conclusione qualitativa.
+- **Figure:** usale ogni volta che chiariscono (struttura, schema, spettro, grafico) e commentale in dettaglio.
+- **Nessun troncamento:** non tagliare per brevità né rimandare l'utente a leggere la tesi al posto di spiegare; se la risposta è lunga, struttura con titoli e chiudi con una sintesi dei punti chiave.
+- Completezza non significa invenzione: ciò che la tesi non riporta resta dichiarato come lacuna.
+
 ## Forma della risposta
 - Struttura con titoli e sottotitoli brevi; apri con una **risposta diretta** (2-4 righe), poi sviluppa: contesto/concetto → dati e risultati → meccanismo/spiegazione → collegamenti con altre parti della tesi → limiti e avvertenze. Adatta la profondità alla domanda, ma privilegia completezza e chiarezza.
 - Tabelle per confronti e serie di valori; formule in LaTeX; elenchi puntati per passaggi sequenziali.

GEMINI.md

@@ -2,4 +2,4 @@
 
 Questo repo è una LLM-wiki in **sola lettura** sulla tesi «Sintesi e caratterizzazione di copolimeri bottle brush foto-elettro attivi». Leggi `CLAUDE.md` alla radice: contiene lo schema completo di consultazione (retrieval dalla wiki e dalle figure, integrazione con conoscenza generale entro il perimetro della tesi, citazioni, difetti noti). Non modificare `wiki/`, `raw/`, `index.md`, `log.md` salvo richiesta esplicita. Rispondi in italiano.
 
-Skill in `.agents/skills/`: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle), `tesi-fonti` (bibliografia).
+Skill in `.agents/skills/`: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle), `tesi-fonti` (bibliografia), `tesi-narrate` (briefing, spiegazione o lezione citati).

README.md

@@ -22,14 +22,27 @@ La tesi è **«Sintesi e caratterizzazione di copolimeri bottle brush foto-elett
 
 ## Architettura
 
+_Il diagramma mostra i tre ingredienti del sistema e come arrivano alla risposta: le fonti (blu) vengono compilate nella wiki (verde); l'agente (rosa) legge la wiki e segue le regole (giallo) per produrre la risposta._
+
 ```mermaid
 flowchart LR
-    R["raw/<br/>fonti immutabili"] --> W["wiki/<br/>pagine collegate"]
-    W --> A["Agente LLM"]
-    S["CLAUDE.md + skill<br/>regole di consultazione"] --> A
-    A --> U["Risposta citata<br/>con figure"]
+    R["raw/<br/>fonti immutabili"] -->|"compilate in"| W["wiki/<br/>pagine collegate"]
+    W -->|"consultata da"| A["Agente LLM"]
+    S["CLAUDE.md + skill<br/>regole di consultazione"] -->|"guidano"| A
+    A -->|"produce"| U["Risposta citata<br/>con figure"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class R fonte
+    class W wiki
+    class S regole
+    class A,U agente
 ```
 
+**Legenda colori (valida per tutti i diagrammi):** 🟦 fonti in `raw/` · 🟩 wiki in `wiki/` · 🟨 regole e skill · 🟪 agente e risposta · ⬜ script. Le frecce con etichetta indicano l'azione che collega due blocchi.
+
 | Livello | Cartella | Ruolo |
 |---|---|---|
 | Fonti | `raw/` | Tesi, riassunto, immagini, catalogo figure, bibliografia. Sola lettura. |
@@ -39,7 +52,7 @@ flowchart LR
 ```
 CLAUDE.md                schema di consultazione (regole RAG)
 AGENTS.md  GEMINI.md     puntatori a CLAUDE.md per Codex, Antigravity, Gemini CLI
-.agents/skills/          tesi-query, tesi-figure, tesi-dati, tesi-fonti
+.agents/skills/          tesi-query, tesi-figure, tesi-dati, tesi-fonti, tesi-narrate
 .claude/skills           link simbolico a .agents/skills (per Claude Code)
 index.md   log.md        catalogo delle pagine e registro delle modifiche
 raw/                     tesi.md, immagini/, immagini.json, bibliografia.json, fonti/, riassunto
@@ -57,20 +70,33 @@ scripts/                 gen_figures.py, gen_bibliografia.py, lint.py
    - «Confronta il band gap elettrochimico dei campioni bottle brush e mostrami i voltammogrammi.»
    - «Come si ottiene lo scheletro DPP-3HT? Mostrami lo schema di sintesi.»
    - «Chi ha proposto il meccanismo di formazione del DPP citato nella tesi?»
-3. Puoi invocare una skill per nome: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle esatti), `tesi-fonti` (bibliografia).
+3. Puoi invocare una skill per nome: `tesi-query` (domande generali), `tesi-figure` (immagini), `tesi-dati` (valori e tabelle esatti), `tesi-fonti` (bibliografia), `tesi-narrate` (briefing, spiegazione o lezione citati).
 
 La wiki è usata **in sola lettura**: l'agente non la modifica salvo richiesta esplicita. Lo schema di manutenzione (ingest, riallineamento, lint) resta nella cronologia git di `CLAUDE.md`, fino al commit `eb672df`.
 
 ## Come è costruito
 
+_Il diagramma segue il materiale dal documento originale alla wiki, in quattro passi da sinistra a destra._
+
 ```mermaid
 flowchart LR
-    T["Tesi<br/>(docx / PDF)"] --> M["MinerU"]
-    M --> R["raw/<br/>testo, immagini,<br/>catalogo, bibliografia"]
-    R --> L["Ingest LLM<br/>per capitolo"]
-    L --> W["wiki/"]
+    T["1 Tesi<br/>docx / PDF"] -->|"estrazione"| M["2 MinerU"]
+    M -->|"Markdown + figure"| R["3 raw/<br/>testo, immagini,<br/>catalogo, bibliografia"]
+    R -->|"lettura per capitolo"| L["4 Ingest LLM"]
+    L -->|"scrive"| W["wiki/<br/>pagine per argomento"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class T,R fonte
+    class M script
+    class L agente
+    class W wiki
 ```
 
+1. **Tesi:** il documento di partenza. 2. **MinerU:** lo converte in Markdown e ritaglia le figure. 3. **`raw/`:** raccoglie il risultato (testo, immagini, catalogo delle figure, bibliografia) e non si modifica più. 4. **Ingest:** un LLM legge `raw/` capitolo per capitolo e scrive la wiki.
+
 - **Estrazione con [MinerU](https://github.com/opendatalab/MinerU).** Strumento open source che converte documenti in Markdown strutturato, con tabelle, formule in LaTeX e figure ritagliate come file immagine. Il suo output è la base di `raw/tesi.md` (1446 righe) e di `raw/immagini/` (file con nome = hash). Il testo è stato poi riallineato alla versione Word della tesi con le convenzioni dello schema di manutenzione. _I parametri usati non sono registrati nel repository._
 - **Catalogo delle figure e bibliografia.** Un catalogo (`raw/immagini.json`) e 63 riferimenti (`raw/bibliografia.json`, schede in `raw/fonti/` con citazione verificata, DOI, abstract e frasi della tesi che li citano).
 - **Compilazione della wiki.** Un LLM legge la tesi capitolo per capitolo e scrive le pagine organizzate **per argomento**, con il localizzatore `tesi_loc` (sezione e righe di `raw/tesi.md`) in ogni pagina.
@@ -80,14 +106,26 @@ flowchart LR
 
 Schemi di sintesi, strutture, spettri e voltammogrammi non si trovano cercando parole, quindi ogni figura è stata resa ricercabile e collegata al testo.
 
+_Il diagramma mostra come i file immagine diventano schede ricercabili: due ingressi (le immagini e il testo della tesi) confluiscono nel catalogo, da cui uno script genera le schede._
+
 ```mermaid
 flowchart LR
-    F["File immagine<br/>da MinerU"] --> C["Catalogo<br/>immagini.json"]
-    T["raw/tesi.md<br/>righe e didascalie"] --> C
-    C --> G["gen_figures.py"]
-    G --> N["wiki/figures/<br/>una scheda per figura"]
+    F["1a File immagine<br/>da MinerU"] -->|"descritti"| C["2 Catalogo<br/>immagini.json"]
+    T["1b raw/tesi.md<br/>righe e didascalie"] -->|"collegate"| C
+    C -->|"letto da"| G["3 gen_figures.py"]
+    G -->|"genera"| N["4 wiki/figures/<br/>una scheda per figura"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class F,T,C fonte
+    class G script
+    class N wiki
 ```
 
+1. **Ingressi:** i file immagine (1a) e il testo della tesi con posizione e didascalia di ogni figura (1b). 2. **Catalogo:** unisce descrizione, testo visibile, composti, concetti e righe di citazione per ogni figura. 3. **Script:** legge il catalogo. 4. **Schede:** una per figura, pronta da cercare e da incorporare in Obsidian.
+
 - **Figure logiche.** I file sono raggruppati in 80 figure della tesi e 11 del riassunto (una figura può avere più pannelli, quindi più file: per questo i conteggi di file e figure non coincidono). Id stabile `fig-NNN`, oppure `fig-x-<hash>` per gli schemi di §3.2 senza numero.
 - **Catalogo `raw/immagini.json`.** Per figura: posizione nella tesi, **didascalia stampata**, descrizione e testo visibile per pannello (scritti guardando l'immagine), composti, concetti, parole chiave, tipo (struttura, schema di reazione, meccanismo, spettro, voltammogramma, grafico, foto…), righe che la citano, confidenza e note di revisione.
 - **Revisione.** Una verifica indipendente segnala le discrepanze (es. didascalia che non descrive l'immagine: Fig. 26, 27, 29, 58, 66, 67, 69); sono segnalate, non corrette. Dopo ogni nuova versione della tesi le immagini sono state confrontate con il Word e quelle vecchie sostituite.
@@ -99,18 +137,38 @@ Solo la didascalia stampata è testo della tesi; il resto deriva dall'immagine e
 
 ## Come risponde a una domanda
 
+_Il diagramma va letto dall'alto in basso: l'agente prima cerca e legge, poi verifica, poi (solo se serve) guarda le figure, infine scrive._
+
 ```mermaid
 flowchart TD
-    Q["Domanda"] --> N["1 Naviga: indice, glossario,<br/>dati, campioni"]
+    Q["Domanda"] --> N["1 Naviga<br/>indice, glossario, dati, campioni"]
     N --> L["2 Legge le pagine intere<br/>e segue i link"]
-    L --> V["3 Verifica i valori su<br/>raw/tesi.md e i difetti noti"]
+    L --> V["3 Verifica i valori<br/>su raw/tesi.md e difetti noti"]
     V --> F{"Servono figure?"}
-    F -->|sì| G["4 Apre la scheda e<br/>guarda l'immagine"]
-    F -->|no| S
-    G --> S["5 Sintesi: tesi prima,<br/>poi conoscenza del modello"]
+    F -->|"sì"| G["4 Apre la scheda<br/>e guarda l'immagine"]
+    F -->|"no"| S
+    G --> S["5 Sintesi<br/>tesi prima, poi conoscenza del modello"]
     S --> O["Risposta con citazioni"]
+    classDef fonte fill:#dbeafe,stroke:#1e40af,color:#111
+    classDef wiki fill:#dcfce7,stroke:#166534,color:#111
+    classDef regole fill:#fef9c3,stroke:#854d0e,color:#111
+    classDef agente fill:#fce7f3,stroke:#9d174d,color:#111
+    classDef script fill:#e5e7eb,stroke:#374151,color:#111
+    class Q,O agente
+    class N,L,S,G agente
+    class V fonte
 ```
 
+Esempio illustrativo (non è una risposta registrata) con la domanda «Perché il PCL evita l'ACQ allo stato solido?»:
+
+| Passo | Cosa fa l'agente |
+|---|---|
+| 1 | Dall'indice individua le pagine su ACQ (`acq-e-stato-solido`), PCL (`rop-pcl`) e bottle brush. |
+| 2 | Le legge per intero e segue i link verso le sottopagine su aggregati H/J e caratterizzazione allo stato solido. |
+| 3 | Controlla i valori su `raw/tesi.md` alle righe indicate da `tesi_loc` e verifica che non ci siano difetti noti. |
+| 4 | Trova la figura pertinente, apre il file in `raw/immagini/` e ne descrive il contenuto. |
+| 5 | Spiega prima ciò che dice la tesi, con citazioni, poi il meccanismo con la conoscenza generale marcata. |
+
 - **Prima la tesi, poi l'integrazione.** I dati vengono dalla wiki e dalla tesi, con posizione (`§4.2, Tab. 14, r.812`) e riferimento bibliografico. La conoscenza generale del modello spiega perché e come, ed è marcata _(conoscenza generale)_; le deduzioni sono _(inferenza)_.
 - **Perimetro.** L'integrazione resta dentro gli argomenti della tesi; fuori perimetro l'agente dice che la tesi non li tratta.
 - **Fedeltà dei dati.** Valori, unità e condizioni copiati alla lettera; valori di condizioni diverse non sono confrontati senza avviso.