# 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 è: ```text 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 `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. 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: ```text 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 `); - 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](../harness/.pi/extensions/tht-gate.js:50) e [tht-gate.js](../harness/.pi/extensions/tht-gate.js:832). ## 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: ```text tht memory search "" --session --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 --json tht session documents --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)