This commit is contained in:
Codex
+57
-189
@@ -1,212 +1,80 @@
|
||||
# Skill operative dell'applicazione
|
||||
# ThothII operating workflow
|
||||
|
||||
## Scopo di questa pagina
|
||||
ThothII guides every question through eight phases. The model proposes the work, the reviewer
|
||||
makes decisions at gates, and the system records persistent artifacts and decisions.
|
||||
|
||||
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["Question"] --> F1["F1 Clarification"]
|
||||
F1 --> F2["F2 Memory"]
|
||||
F2 --> F3["F3 Rewriting"]
|
||||
F3 --> F4["F4 Evidence"]
|
||||
F4 --> F5["F5 Schema"]
|
||||
F5 --> F6["F6 CTE plan"]
|
||||
F6 --> F7["F7 SQL"]
|
||||
F7 --> F8["F8 Promotion"]
|
||||
F8 --> DONE["Finalized session"]
|
||||
```
|
||||
|
||||
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.
|
||||
## Workflow principles
|
||||
|
||||
## Che cos'è `tht-sessione`
|
||||
- The model proposes; the reviewer approves, corrects, or rejects.
|
||||
- The session ledger records every material decision.
|
||||
- Persisted state is the source of truth.
|
||||
- A phase advances only when its artifacts and gates are complete.
|
||||
- Resume rebuilds context from persisted artifacts, not from the conversation.
|
||||
|
||||
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: clarification
|
||||
|
||||
Non è una semplice raccolta di suggerimenti per il modello. È il contratto operativo che stabilisce:
|
||||
The system identifies the ambiguity most likely to change the meaning of the question and presents
|
||||
one decision at a time. Mutually exclusive interpretations use a single choice; multiple valid
|
||||
answers use a multiple choice.
|
||||
|
||||
- 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.
|
||||
The system proposes Memory items that fit the question. Selected items enter the current session
|
||||
context; unselected items remain available for future questions.
|
||||
|
||||
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: rewriting
|
||||
|
||||
## Come viene caricata
|
||||
The system rewrites the question explicitly using the approved clarifications. The reviewer checks
|
||||
the resulting question and its assumptions before continuing.
|
||||
|
||||
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
|
||||
```
|
||||
The system retrieves Evidence from the active corpus and presents citations and provenance. The
|
||||
reviewer decides which items apply to the question.
|
||||
|
||||
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.
|
||||
Tables, columns, relationships, and filters are linked to the approved meaning of the question.
|
||||
The summary closes the phase when the question, assumptions, and DWH elements are consistent.
|
||||
|
||||
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: CTE plan
|
||||
|
||||
Riferimenti implementativi: [tht-gate.js](../harness/.pi/extensions/tht-gate.js:50) e [tht-gate.js](../harness/.pi/extensions/tht-gate.js:832).
|
||||
The query is broken into named CTEs with a purpose, dependencies, tables, filters, and output
|
||||
columns. The reviewer sees each step before the system produces the final SQL.
|
||||
|
||||
## Rapporto tra skill, workflow e gate
|
||||
## F7: final SQL
|
||||
|
||||
I tre componenti hanno responsabilità diverse:
|
||||
The system produces `sql_final.sql`, checks it against the approved plan, and presents the artifact
|
||||
to the reviewer. A correction can reopen the CTE plan without discarding decisions that remain valid.
|
||||
|
||||
| Componente | Responsabilità |
|
||||
## F8: Memory promotion
|
||||
|
||||
At the end of the session, the system proposes reusable clarifications. The reviewer decides which
|
||||
ones to promote to the global registry, and the session is then finalized.
|
||||
|
||||
## Available gates
|
||||
|
||||
| Gate | Use |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
| Single choice | Only one interpretation can be valid |
|
||||
| Multiple choice | Several items can be valid at the same time |
|
||||
| Artifact confirmation | Approval of a document or phase result |
|
||||
| Phase confirmation | Explicitly closes a phase |
|
||||
|
||||
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`.
|
||||
## Resume and reopening
|
||||
|
||||
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)
|
||||
A resumed session returns to its last incomplete phase. Reopening invalidates only the decisions
|
||||
and artifacts that depend on the changed point; the rest of the work remains valid.
|
||||
|
||||
Reference in New Issue
Block a user