11 KiB
Skill operative dell'applicazione
Scopo di questa pagina
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 è:
harness/.pi/skills/tht-sessione/SKILL.md
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.
Che cos'è tht-sessione
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.
Non è una semplice raccolta di suggerimenti per il modello. È il contratto operativo che stabilisce:
- quali passaggi devono essere eseguiti;
- quali comandi
thtusare; - 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.
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.
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.
Come viene caricata
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:
harness/.pi/extensions/tht-gate.js
└── ../skills/tht-sessione/SKILL.md
Il gate aggiunge inoltre istruzioni di kickoff per distinguere:
- nuova sessione (
/nuova-domanda); - ripresa (
/riprendi-sessione <id>); - sessione già creata con id noto;
- contesto di retrieval già fornito dal backend.
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.
Riferimenti implementativi: tht-gate.js e tht-gate.js.
Rapporto tra skill, workflow e gate
I tre componenti hanno responsabilità diverse:
| Componente | Responsabilità |
|---|---|
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 |
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.
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:
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_selectoreviewer_decideregistra 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:
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.mdper la domanda riscritta;cte.mdper la progettazione dei CTE;sql-generation.mdper 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.