From b9affd9befed77fae70dd63c55b94cb250345ea1 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Tue, 20 Oct 2026 14:38:49 +0200 Subject: [PATCH] Aggiunge tesi-narrate, regola di completezza delle risposte e diagrammi del README piu leggibili Co-Authored-By: Claude Sonnet 5.5 --- .agents/skills/tesi-narrate/SKILL.md | 31 +++++++++ .agents/skills/tesi-query/SKILL.md | 5 +- AGENTS.md | 2 +- CLAUDE.md | 10 +++ GEMINI.md | 2 +- README.md | 96 ++++++++++++++++++++++------ 6 files changed, 124 insertions(+), 22 deletions(-) create mode 100644 .agents/skills/tesi-narrate/SKILL.md diff --git a/.agents/skills/tesi-narrate/SKILL.md b/.agents/skills/tesi-narrate/SKILL.md new file mode 100644 index 0000000..c184f2a --- /dev/null +++ b/.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 +` [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. diff --git a/.agents/skills/tesi-query/SKILL.md b/.agents/skills/tesi-query/SKILL.md index a803f30..1780bb5 100644 --- a/.agents/skills/tesi-query/SKILL.md +++ b/.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). diff --git a/AGENTS.md b/AGENTS.md index da6c1ea..597407c 100644 --- a/AGENTS.md +++ b/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). diff --git a/CLAUDE.md b/CLAUDE.md index 5d5d9ae..83b7ee6 100644 --- a/CLAUDE.md +++ b/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. diff --git a/GEMINI.md b/GEMINI.md index b20f899..d8c5991 100644 --- a/GEMINI.md +++ b/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). diff --git a/README.md b/README.md index 008279c..980723b 100644 --- a/README.md +++ b/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/
fonti immutabili"] --> W["wiki/
pagine collegate"] - W --> A["Agente LLM"] - S["CLAUDE.md + skill
regole di consultazione"] --> A - A --> U["Risposta citata
con figure"] + R["raw/
fonti immutabili"] -->|"compilate in"| W["wiki/
pagine collegate"] + W -->|"consultata da"| A["Agente LLM"] + S["CLAUDE.md + skill
regole di consultazione"] -->|"guidano"| A + A -->|"produce"| U["Risposta citata
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
(docx / PDF)"] --> M["MinerU"] - M --> R["raw/
testo, immagini,
catalogo, bibliografia"] - R --> L["Ingest LLM
per capitolo"] - L --> W["wiki/"] + T["1 Tesi
docx / PDF"] -->|"estrazione"| M["2 MinerU"] + M -->|"Markdown + figure"| R["3 raw/
testo, immagini,
catalogo, bibliografia"] + R -->|"lettura per capitolo"| L["4 Ingest LLM"] + L -->|"scrive"| W["wiki/
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
da MinerU"] --> C["Catalogo
immagini.json"] - T["raw/tesi.md
righe e didascalie"] --> C - C --> G["gen_figures.py"] - G --> N["wiki/figures/
una scheda per figura"] + F["1a File immagine
da MinerU"] -->|"descritti"| C["2 Catalogo
immagini.json"] + T["1b raw/tesi.md
righe e didascalie"] -->|"collegate"| C + C -->|"letto da"| G["3 gen_figures.py"] + G -->|"genera"| N["4 wiki/figures/
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-` 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,
dati, campioni"] + Q["Domanda"] --> N["1 Naviga
indice, glossario, dati, campioni"] N --> L["2 Legge le pagine intere
e segue i link"] - L --> V["3 Verifica i valori su
raw/tesi.md e i difetti noti"] + L --> V["3 Verifica i valori
su raw/tesi.md e difetti noti"] V --> F{"Servono figure?"} - F -->|sì| G["4 Apre la scheda e
guarda l'immagine"] - F -->|no| S - G --> S["5 Sintesi: tesi prima,
poi conoscenza del modello"] + F -->|"sì"| G["4 Apre la scheda
e guarda l'immagine"] + F -->|"no"| S + G --> S["5 Sintesi
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.