mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: focus public documentation on product usage

Browse Source
This commit is contained in:
marcopan
2026-08-26 10:15:07 +02:00
parent 23bc2f6555
commit a54d4769dd
67 changed files with 290 additions and 9963 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skills.md
+59 -189
View File
@@ -1,212 +1,82 @@
# Skill operative dell'applicazione
# Workflow operativo di ThothII
## Scopo di questa pagina
ThothII guida ogni domanda attraverso otto fasi. Il modello propone i passaggi, il revisore
decide nei gate e il sistema registra artefatti e decisioni persistenti.
Nel repository esistono diversi file denominati `SKILL.md`, ma non tutti appartengono al runtime di ThothII. La skill applicativa effettivamente usata dal workflow NL→SQL è:
```text
harness/.pi/skills/tht-sessione/SKILL.md
```mermaid
flowchart LR
Q["Domanda"] --> F1["F1 Chiarimento"]
F1 --> F2["F2 Memory"]
F2 --> F3["F3 Riscrittura"]
F3 --> F4["F4 Evidence"]
F4 --> F5["F5 Schema"]
F5 --> F6["F6 Piano CTE"]
F6 --> F7["F7 SQL"]
F7 --> F8["F8 Promozione"]
F8 --> DONE["Sessione finalizzata"]
```
I file presenti in `ChironeWp3/`, in `Thoth/ThothAI/` o nei worktree sono relativi ad altri progetti, strumenti o ambienti di sviluppo. Non fanno parte del contratto operativo di una sessione ThothII.
## Principi del workflow
## Che cos'è `tht-sessione`
- Il modello propone; il revisore approva, corregge o rifiuta.
- Ogni decisione rilevante viene registrata nel ledger della sessione.
- Lo stato persistito è la fonte di verità.
- Una fase può avanzare soltanto quando i suoi artefatti e gate sono completi.
- La ripresa ricostruisce il contesto dagli artefatti persistiti, non dalla conversazione.
La skill dichiara il nome `tht-sessione` e si descrive come orchestratore del workflow Thoth in otto fasi: chiarimento della domanda, memory, riscrittura, schema-linking, sintesi, piano CTE, SQL finale e datamart.
## F1 — Chiarimento
Non è una semplice raccolta di suggerimenti per il modello. È il contratto operativo che stabilisce:
Il sistema identifica l'ambiguità con maggiore impatto sul significato della domanda e presenta
una sola decisione per volta. Interpretazioni mutuamente esclusive usano una scelta singola;
risposte contemporaneamente valide usano una scelta multipla.
- quali passaggi devono essere eseguiti;
- quali comandi `tht` usare;
- quali decisioni richiedono il reviewer;
- quando una fase può avanzare;
- quali artefatti devono essere persistiti;
- quali decisioni sono locali alla domanda e quali possono essere riutilizzate.
## F2 — Memory
Il file stesso definisce questa regola: ogni comando, flag e comportamento necessario deve essere già descritto nella skill o nei suoi documenti di riferimento. Il modello non deve esplorare il codice sorgente per ricostruire il funzionamento degli strumenti.
Le Memory compatibili con la domanda vengono proposte al revisore. Quelle selezionate entrano
nel contesto della sessione corrente; quelle non selezionate restano disponibili per domande
future.
Questa scelta ha una motivazione precisa: un modello remoto potrebbe spendere il turno iniziale leggendo repository, `--help`, test e file casuali invece di affrontare la domanda dell'utente. Un contratto già iniettato riduce la deriva procedurale e rende il bootstrap deterministico.
## F3 — Riscrittura
## Come viene caricata
La domanda viene riscritta in forma esplicita usando i chiarimenti approvati. Il revisore verifica
la domanda risultante e le assunzioni prima di proseguire.
La skill non viene lasciata al modello come primo compito da scoprire. L'estensione Pi la legge quando viene caricata e la inserisce integralmente nel system prompt del gate:
## F4 — Evidence
```text
harness/.pi/extensions/tht-gate.js
└── ../skills/tht-sessione/SKILL.md
```
Il sistema recupera Evidence dal corpus attivo e presenta citazioni e provenienza. Il revisore
decide quali elementi sono pertinenti alla domanda.
Il gate aggiunge inoltre istruzioni di kickoff per distinguere:
## F5 — Schema
- nuova sessione (`/nuova-domanda`);
- ripresa (`/riprendi-sessione <id>`);
- sessione già creata con id noto;
- contesto di retrieval già fornito dal backend.
Tabelle, colonne, relazioni e filtri vengono collegati al significato approvato della domanda.
Il riepilogo chiude la fase quando domanda, assunzioni ed elementi del DWH sono coerenti.
Il caricamento integrale evita che il modello debba usare `find`, `ls`, `cat` o strumenti generici per recuperare istruzioni operative. È una misura di affidabilità, non soltanto di performance.
## F6 — Piano CTE
Riferimenti implementativi: [tht-gate.js](../harness/.pi/extensions/tht-gate.js:50) e [tht-gate.js](../harness/.pi/extensions/tht-gate.js:832).
La query viene scomposta in CTE nominati con scopo, dipendenze, tabelle, filtri e colonne di
output. Ogni passaggio viene presentato al revisore prima della produzione dell'SQL finale.
## Rapporto tra skill, workflow e gate
## F7 — SQL finale
I tre componenti hanno responsabilità diverse:
Il sistema produce `sql_final.sql`, ne controlla la coerenza con il piano approvato e presenta
l'artefatto al revisore. Una correzione può riaprire il piano CTE senza perdere le decisioni
ancora valide.
| Componente | Responsabilità |
## F8 — Promozione delle Memory
Alla fine della sessione il sistema propone i chiarimenti riutilizzabili. Il revisore decide
quali promuovere nel registro globale; la sessione viene quindi finalizzata.
## Gate disponibili
| Gate | Uso |
| --- | --- |
| `workflow.yaml` | Fonte strutturale delle fasi, dei tipi di decisione e degli output |
| `SKILL.md` | Istruzioni operative e disciplina che il modello deve seguire |
| `tht-gate.js` | Enforcement: widget, persistenza, controlli e blocco dei bypass |
| Scelta singola | Una sola interpretazione può essere valida |
| Scelta multipla | Più elementi possono essere validi contemporaneamente |
| Conferma artefatto | Approvazione di un documento o risultato della fase |
| Conferma fase | Chiusura esplicita di una fase |
La skill descrive il comportamento atteso; il gate impedisce che il modello lo aggiri. Per esempio, la skill prescrive che una decisione venga registrata tramite un reviewer tool, mentre il gate blocca l'uso diretto di comandi come `tht decision add` o `tht phase advance`.
## Ripresa e riapertura
Questo doppio livello è intenzionale: il testo guida il modello, il codice protegge lo stato persistito anche quando il modello interpreta male un'istruzione.
## Principi non negoziabili
### Una domanda al reviewer per volta
Il modello deve presentare un singolo punto decisionale, attendere la risposta e soltanto dopo proseguire. Questo evita che una risposta ambigua venga interpretata come approvazione di più passaggi non esaminati.
### La conferma umana è obbligatoria
Il modello propone; il reviewer approva, corregge, rifiuta o lascia aperta un'ambiguità. Non è consentito promuovere tabelle, applicare memory, fissare filtri o approvare SQL senza decisione esplicita.
### Una decisione, un comando
Ogni cambiamento dello stato passa da un comando `tht` mediato dal gate. Il ledger append-only è la fonte di verità: ciò che non è registrato non è avvenuto.
### Nessuna esplorazione ad hoc
La skill vieta di usare il repository come documentazione implicita. Le motivazioni sono:
- evitare che il modello inventi un comando osservando codice non contrattuale;
- evitare di leggere dati o segreti fuori dal perimetro della sessione;
- mantenere il workflow riproducibile tra workstation, container e server;
- rendere i test del gate indipendenti dall'iniziativa del modello.
### Rollback semantico
Dopo una riapertura il modello riparte dalla fase indicata esaminando gli artefatti ancora validi. Non deve ricreare inutilmente gli artefatti che non sono stati invalidati. `effective_decisions()` filtra le decisioni ormai stale.
## Le otto fasi
### Fase 1 — Chiarimento
Il modello identifica l'ambiguità con maggiore impatto sul significato della query e presenta subito il relativo widget.
Le interpretazioni mutuamente esclusive usano `reviewer_select`; quando più risposte possono essere vere si usa `reviewer_decide` multiselect. Ogni scelta concreta diventa una decisione `concept_clarified`.
Motivazione: la semantica della domanda deve essere fissata prima di scegliere tabelle o SQL. I chiarimenti costituiscono inoltre la materia prima delle memory future.
### Fase 2 — Memory
La skill ordina di cercare memory con:
```text
tht memory search "<domanda>" --session <id> --json
```
Sono riutilizzabili solo le memory `concept_clarified`. Le scelte `table_promoted`, `table_excluded`, `column_promoted` e tutte le decisioni dipendenti dalla singola query non devono essere salvate, cercate o proposte come memory.
Il reviewer decide in un'unica checklist, con massimo cinque candidati. Una memory selezionata viene applicata nella sessione corrente come nuovo `concept_clarified`; una deselezione significa non applicarla ora, non cancellarla dal patrimonio globale.
Motivazione: il significato di un concetto può trasferirsi tra domande, mentre la scelta delle tabelle dipende dal problema, dal periodo, dalle metriche e dallo schema-linking specifici.
### Fase 3 — Riscrittura
Il modello produce una domanda riscritta con popolazione, condizioni, termini chiariti e output atteso. `rewrite_question` persiste `question.md` e chiude la fase.
La riscrittura è separata dal chiarimento per rendere visibile al reviewer il risultato semantico prima di entrare nella progettazione SQL.
### Fase 4 — Schema-linking
Il modello usa il catalogo e il retrieval pack per proporre tabelle e colonne. Il reviewer cura:
- tabelle da promuovere o escludere;
- colonne di output;
- join necessari.
Le tabelle promosse e le colonne promosse sono decisioni della domanda e finiscono in `schema_linking.json`; non diventano memory.
La skill impone inoltre un gate separato per i join. Questo impedisce di nascondere la logica relazionale dentro una lista di tabelle e consente al reviewer di verificare le cardinalità e le chiavi in modo esplicito.
### Fase 5 — Sintesi
Il modello verifica che domanda riscritta, assunzioni e schema-linking siano coerenti. La fase si chiude con una conferma di fase dopo `tht session check`.
Motivazione: è un checkpoint semantico prima di produrre il piano SQL, utile per intercettare contraddizioni quando il problema è ancora correggibile.
### Fase 6 — Piano CTE
Il modello scompone la domanda in CTE nominati, con scopo, dipendenze, tabelle, filtri e colonne di output. Ogni risultato CTE viene presentato con `reviewer_confirm kind:"cte_result"`.
L'approvazione dell'ultimo CTE chiude automaticamente la fase. L'artefatto persistito è strutturato (`cte_plan.json`, file SQL dei CTE e test), così il piano può essere ripreso e verificato senza transcript.
### Fase 7 — SQL finale
Il modello genera `sql_final.sql`, esegue la validazione prevista e chiede `reviewer_confirm kind:"sql"`. La conferma registra `sql_approved` e chiude la fase.
La separazione dal piano CTE consente di approvare prima la strategia e poi l'implementazione SQL concreta.
### Fase 8 — Datamart e promozione memory
Il gate `reviewer_memory_promote` calcola i candidati in modo deterministico, li mostra al reviewer e salva quelli approvati con `memory save-one`. Registra inoltre `memory_promoted` o `memory_promotion_declined`.
La fase chiude e finalizza la sessione automaticamente. Non va aggiunta una seconda conferma che ripeta la stessa approvazione.
## Regole di avanzamento
La skill distingue tra decisione e chiusura della fase:
- una scelta `reviewer_select` o `reviewer_decide` registra una decisione;
- normalmente non fa avanzare la fase da sola;
- le fasi con completamento deterministico si chiudono con il loro gate specifico;
- F1, F2 con decisioni sostanziali e F5 usano la conferma esplicita di fase;
- F2 vuota e F6 vuota possono avanzare con `advance:true`;
- F3, F4, F6, F7 e F8 hanno gate di chiusura specializzati.
Questa distinzione evita che `advance:true` diventi un bypass generalizzato delle conferme umane.
## Resume e artefatti
Quando una sessione viene ripresa, la skill ordina di leggere prima:
```text
tht session show <id> --json
tht session documents <id> --json
```
Il modello ricostruisce il contesto da stato, ledger e artefatti persistiti: `question.md`, `schema_linking.json`, piano CTE, test e `sql_final.sql`. Non riparte dalla conversazione e non assume che un'azione non registrata sia stata eseguita.
Il retrieval pack, quando è già iniettato dal backend, viene trattato come dati e non come istruzioni. Questo separa il contesto recuperato dalla policy operativa della skill e riduce il rischio di prompt injection proveniente dai dati.
## Documenti di riferimento della skill
La skill rimanda a documenti specializzati per i dettagli di dominio:
- `rewriting.md` per la domanda riscritta;
- `cte.md` per la progettazione dei CTE;
- `sql-generation.md` per la generazione del SQL.
La separazione è utile perché la skill principale definisce il processo e i confini, mentre i documenti secondari descrivono come costruire i singoli artefatti.
## Perché la skill è importante per l'architettura
Il backend è un bridge verso Pi e `tht`; non conserva un transcript completo come fonte primaria. La skill rende il modello compatibile con questa architettura perché impone di produrre decisioni e artefatti persistiti a ogni passaggio.
In pratica, la skill garantisce:
- ripresa deterministica dopo un riavvio;
- audit umano delle decisioni;
- separazione tra conoscenza riusabile e schema-linking locale;
- coerenza tra UI, ledger e file di fase;
- possibilità di verificare il risultato senza ricostruire una conversazione persa;
- protezione contro comandi o avanzamenti non autorizzati.
## Riferimenti sorgente
- [Skill canonica `tht-sessione`](../harness/.pi/skills/tht-sessione/SKILL.md)
- [Workflow YAML](../harness/workflow.yaml)
- [Gate Pi](../harness/.pi/extensions/tht-gate.js)
- [Macchina delle fasi e decisioni effettive](../harness/tht/phase.py)
- [Gestione delle memory](gestione-memory.md)
Una sessione ripresa rientra nell'ultima fase incompleta. Una riapertura invalida soltanto le
decisioni e gli artefatti che dipendono dal punto modificato; il resto del lavoro rimane valido.