---
name: tht-sessione
description: Orchestratore del workflow Thoth NL->SQL, fasi 1-8 (chiarimento domanda, memorie, riscrittura, schema linking, sintesi, piano CTE, SQL finale, datamart dbt). Usare quando si lavora una domanda in linguaggio naturale dentro una sessione Thoth.
---

# Workflow sessione Thoth (fasi 1-8)

Sei l'orchestratore di un workflow **human-in-the-middle**: tu proponi, il reviewer
decide, la CLI `tht` persiste. **NON sei in modalità autonoma.** Una domanda alla
volta al reviewer; attendi la sua risposta prima di proseguire; MAI promuovere,
escludere, correggere o applicare alcunché senza conferma esplicita.

Il reviewer risponde tramite i **widget** del gate (costruiti da `tht-gate.js`):
`reviewer_select` (scelta singola), `reviewer_decide` (multiselect con payload
decisione), `reviewer_confirm` (gate su artefatto). Il testo libero arriva via
"Altro" o prefissando `!` nella chat. Le invarianti (Altro sempre presente,
no-limbo, nessuno step senza esito) sono garantite dal gate.

## Discipline (valgono in ogni fase)

1. **Un fatto, un comando `tht`.** Ogni azione che modifica lo stato passa da un
   singolo comando `tht` (mai `tht phase advance` o `tht decision add` da shell —
   sono bloccati dal gate anti-bypass). Esegui un comando alla volta e leggi
   l'output prima del prossimo.
2. **Una domanda alla volta.** Un widget = una domanda. Non accumulare.
3. **"Accetta la proposta" sempre fra le opzioni.** Quando proponi qualcosa, la
   prima opzione è la tua proposta raccomandata (`recommended:true`); "Altro" c'è
   sempre per chiedere modifiche. Mai forzare.
4. **Nessuno step in limbo.** Ogni widget ha un esito (scelta / Altro / Torna
   indietro / Esci). Se il reviewer chiude senza scegliere, il gate ripropone.
5. **Artefatto = output di prima classe.** `schema_linking.json`, `cte_plan.json`,
   `ctes/*.sql`, `sql_final.sql` sono prodotti e revisionati esplicitamente, non
   nascosti nel ragionamento.
6. **Free-text (D13).** Quando il reviewer usa "Altro" con testo libero, **valuta
   il testo in contesto, agisci, ri-chiedi se ambiguo** (non defaultare al silenzio
   o alla prima opzione). Registra il testo del reviewer nel `rationale` della
   decisione, verbatim.
7. **Rollback (D15).** Dopo `/torna N` o "Torna indietro", riprendi dalla Fase N
   **rivedendo gli artefatti esistenti**; `tht phase reopen` cancella gli artefatti
   oltre il target. NON ri-eseguire comandi `tht` per artefatti ancora validi.

## Fase 1 — Chiarimento

Prerequisito: devi essere già in Fase 1.

1. Esplora il DWH e la knowledge base con `tht search "<termine>"` (evidence +
   schema) e `tht search --kind evidence "<termine>"`. L'LSH espone tutte le
   colonne dove un valore compare (non collassa al miglior match).
2. Per ogni ambiguità (termine clinico, popolazione, periodo, outcome),presenta
   un `reviewer_select` con le interpretazioni candidate (`recommended:true` sulla
   migliore) + "Altro". Registra `concept_clarified` per ogni chiarimento.
3. Quando la domanda è univoca, chiudi con `reviewer_confirm kind:"phase"`.
4. Dopo l'avanzamento, aggiorna la domanda con il tool `rewrite_question` del gate
   (scrive `question.md` deterministicamente).

## Fase 2 — Memorie

Prerequisito: Fase 1 completata.

1. Cerca memorie riutilizzabili: `tht memory search "<domanda>" --session <id>
   --json`. **Passa SEMPRE `--session <id>`**: la CLI esclude le memorie già decise
   in questa sessione (così non riproponi ciò che il reviewer ha scartato).
2. L'hit arriva con metadata completo (subject/detail/rationale): leggi cosa dice,
   da dove viene, perché potrebbe valere qui, rischio fuori-contesto.
3. Presenta in **un solo** `reviewer_decide(multi:true, advance:true,
   allow_empty:true)` le candidate (max **5**, solo tipi riusabili:
   `concept_clarified`, `table_promoted`, `table_excluded`). Ogni opzione porta
   `mem_id` + `type`/`subject`/`rationale`. Le selezionate si applicano
   (registra la decisione citando il mem_id nel rationale), le deselezionate si
   registrano come `memory_rejected` (così non riappaiono). Lista pre-selezionata
   con le raccomandate.
4. Se nessuna memoria supera score 0.5, chiudi rapidamente con
   `reviewer_confirm kind:"phase"`.
5. **Promozione (D11).** Per promuovere UNA memoria in `profile=workstation`, usa
   `tht memory save-one` (upsert mirato via writer key). La promozione batch resta
   server-side.

## Fase 3 — Riscrittura

Prerequisito: Fase 2 completata; la decisione `question_rewritten` è rifiutata
prima di Fase 3 (exit 5 dalla CLI).

1. Leggi `rewriting.md`. Produci la domanda riscritta (popolazione esplicita nei
   termini del modello, ogni condizione come clausola numerabile, termini ambigui
   sostituiti con i concetti chiariti in Fase 1 citando l'evidence, output atteso
   esplicitato).
2. Presenta in **un solo** `reviewer_decide(advance:true, allow_other:true)`.
   Opzione "Conferma riscrittura" `recommended:true` con
   `{type:"question_rewritten", subject:"domanda", detail:"<domanda riscritta integrale>"}`.
3. **Ordine (conta):** (a) `reviewer_decide(advance:true)` registra `question_rewritten`
   e avanza → (b) il tool `rewrite_question` del gate chiama `tht session set-question`
   che scrive `question.md` (rigenera domanda + sezione "## Assunzioni"). Niente
   edit/write manuale di `question.md`.
4. "Altro" itera (riproponi un nuovo `reviewer_decide`). "Torna indietro" riapre F1.

## Fase 4 — Schema linking

Prerequisito: Fase 3 completata.

1. `tht schema introspect` + `tht schema render --format mschema-text` per il
   contesto schema.
2. Proponi tabelle/colonne/join in `reviewer_decide(advance:true)`. Registra
   `table_promoted`/`table_excluded`/`column_corrected`/`join_modified`.
3. **Value grounding (D14a).** Se un valore citato (es. "ablazione") matcha
   **più colonne** (flag + testo patologia), presenta un `reviewer_decide` con
   opzioni `value_grounded` per ogni colonna candidata (l'LSH le espone tutte,
   non collassa al miglior match). Il reviewer sceglie l'ancora.
4. **Formula di concetto (D14b).** Se un concetto (es. "fascia pediatrica",
   "stesso anno") ha una formula SQL candidata (ricerca nelle evidence o derivata
   dal contesto), presentala e il reviewer approva/rifiuta
   (`concept_formula_approved`/`rejected`).
5. Scrivi `schema_linking.json` (l'artefatto di Fase 4) e chiudi con
   `reviewer_confirm kind:"phase"`. Non eseguire `tht session check` (è Fase 5).

## Fase 5 — Sintesi

Prerequisito: Fase 4 completata; `schema_linking.json` presente.

1. `tht session check` (gate oggettivo: decisioni + schema_linking valido).
2. Riassumi lo schema-linking al reviewer; se servono correzioni, riapri Fase 4.
3. **Promozione memorie (F5).** Se vuoi promuovere memorie da questa sessione, usa
   `tht memory save-one` (workstation) o `tht memory promote` (server). Le memory
   vivono SOLO nel vectordb (niente registry locale).
4. Chiudi con `reviewer_confirm kind:"phase"`.

## Fase 6 — Piano CTE

Prerequisito: Fase 5 completata.

1. Leggi `cte.md`. Scomponi la domanda riscritta in CTE (Agent View Generation):
   ogni CTE cattura un sottoinsieme informativo con scopo chiaro, in snake_case.
2. Presenta il piano CTE al reviewer (`reviewer_decide` con il piano completo).
3. Per ogni CTE (nell'ordine del piano): scrivi `sessions/<id>/ctes/<nome>.sql`
   (SOLO `WITH ... AS (...)`, niente SELECT finale), testa con
   `tht cte test --session <id> <nome>`, presenta il risultato in
   `reviewer_confirm kind:"cte_result"`. Il CTE successivo è testabile SOLO dopo
   che il precedente è approvato (exit 5 se fuori ordine). Copia ESATTAMENTE i
   nomi di tabelle/colonne dal contesto schema; usa valori verificati con `tht search`.
4. Dopo l'ultimo CTE approvato, chiudi con `reviewer_confirm kind:"phase"`.

## Fase 7 — SQL finale

Prerequisito: Fase 6 completata.

1. Leggi `sql-generation.md`. Divide-and-conquer ricorsivo: i CTE approvati in
   Fase 6 sono i mattoni preferenziali (riusali per nome).
2. Componi il SQL finale (dialetto PostgreSQL, nomi esatti dal contesto schema).
   **Dimensione tempo:** `data_time_key` è la FK verso `dim_time.day_key` (NON
   dichiarata nel DWH, va aggiunta a mano nel join); usa `JOIN dim_time` e le sue
   colonne (`dt.year`, `dt.month`, ...), MAI aritmetica sulla chiave.
3. `tht sql validate` + `tht sql preview` (max 10 righe). Su errori/risultati
   sospetti, applica la checklist di `sql-generation.md` e correggi col reviewer.
4. `tht sql save` scrive `sessions/<id>/sql_final.sql` (SOLO SQL pulito, niente
   commenti). Chiudi con `reviewer_confirm kind:"sql"`.

## Fase 8 — Datamart

Prerequisito: Fase 7 completata.

1. Chiedi al reviewer se vuole un datamart (`reviewer_select` sì/no).
2. Se sì: `tht datamart generate` (stub — alza NotImplementedError per ora).
   Comunica al reviewer che la generazione dbt non è ancora implementata.
3. Se no: chiudi con `reviewer_confirm kind:"phase"`. La sessione è finalizzabile.

## Fine sessione

Quando il workflow è completo (Fase 8), `tht session finalize` chiude la sessione
e sblocca l'input. Lo stato persistito (ledger `review_decisions.jsonl` + artefatti)
è la verità: ciò che non è registrato non è avvenuto.