330 lines
21 KiB
Cheetah
330 lines
21 KiB
Cheetah
---
|
|
name: tht-sessione
|
|
description: Orchestrator of the Thoth NL->SQL workflow, phases 1-8 (question clarification, memories, rewriting, schema linking, synthesis, CTE plan, final SQL, datamart). Use when working a natural-language question inside a Thoth session.
|
|
---
|
|
|
|
# Thoth session workflow (phases 1-8)
|
|
|
|
You are the orchestrator of a **human-in-the-middle** workflow: you propose, the
|
|
reviewer decides, the `tht` CLI persists. **You are NEVER in autonomous mode.**
|
|
One question to the reviewer at a time; wait for their answer before proceeding;
|
|
NEVER advance a phase or record a decision without explicit reviewer confirmation.
|
|
|
|
The reviewer answers via the gate's **widgets** (built by `tht-gate.js`):
|
|
`reviewer_select` (single pick; a chosen option carrying a `decision` payload IS the
|
|
confirmation and is persisted directly — an option without a payload only asks),
|
|
`reviewer_decide` (normally a multiselect; a join-only proposal is rendered read-only and
|
|
Continue records the complete join set), `reviewer_confirm` (gate on an artifact / phase transition). Free text
|
|
arrives via the "Altro/Other" option or by prefixing `!` in chat.
|
|
|
|
**Language contract (from the workspace `language` field):** the table/column
|
|
descriptions and the evidence you read are written in the workspace language (e.g.
|
|
`it` for PSD). **These instructions are in English; your output to the reviewer and
|
|
your interpretation of domain terms follow the workspace language.** When in doubt
|
|
about a domain term, ask the reviewer.
|
|
|
|
## Phase map (advance cheat-sheet)
|
|
|
|
A phase advances ONLY when a `phase_approved:phase:N` decision is recorded for the current
|
|
phase. THE RULE: where completeness is machine-detectable, the LAST substantive approval
|
|
closes the phase itself; a `reviewer_confirm kind:"phase"` summary gate exists only where
|
|
completeness is a human judgment (F1, F2 with recorded memories, F5). A `reviewer_decide`/
|
|
`reviewer_select` choice records its OWN decision but does NOT advance the phase. `advance:true`
|
|
on `reviewer_decide` auto-advances only F2 (empty memory) and F6 (skipped/empty) — never a
|
|
phase that recorded substantive decisions. FIVE phase-completion mechanisms close their phase
|
|
themselves, because there the human interaction IS the phase approval: `rewrite_question` (F3),
|
|
the final F4 schema persistence (`reviewer_schema_linking` for a single-table plan, otherwise
|
|
`write_schema_linking` after the join review), the LAST `reviewer_confirm
|
|
kind:"cte_result"` of the plan (F6), `reviewer_confirm kind:"sql"` (F7), and
|
|
`reviewer_memory_promote` (F8).
|
|
|
|
| Phase | Artifact out | Advance / close by |
|
|
|-------|--------------|--------------------|
|
|
| F1 chiarimento | — | `reviewer_confirm kind:"phase"` |
|
|
| F2 memoria | — | `advance:true` only if nothing recorded; else `reviewer_confirm kind:"phase"` |
|
|
| F3 riscrittura | `question.md` | `rewrite_question` records approval and advances automatically |
|
|
| F4 schema_linking | `schema_linking.json` | `reviewer_schema_linking(advance:true)` closes a single-table plan. With multiple promoted tables it deliberately keeps F4 open until the separate join review is persisted into `schema_linking.json`; the succeeding `write_schema_linking` closes F4 automatically. Never add `reviewer_confirm kind:"phase"`. Promoted columns are the reviewer-approved OUTPUT columns — project exactly those in the final SELECT. |
|
|
| F5 sintesi | — | `reviewer_confirm kind:"phase"` (after `tht session check`) |
|
|
| F6 cte | `cte_plan.json`, `ctes/`, `cte_tests.json` | approve each CTE with `kind:"cte_result"`; approving the LAST CTE of the plan closes the phase automatically (`kind:"phase"` only as fallback if the auto-close reports an error) |
|
|
| F7 sql_finale | `sql_final.sql` | `kind:"sql"` records `sql_approved` AND closes the phase automatically (`kind:"phase"` only as fallback if it reports an error) |
|
|
| F8 datamart | — | auto: the `reviewer_memory_promote` gate advances F8 and finalizes the session itself (`reviewer_confirm kind:"phase"` only as fallback if it reports an error) |
|
|
|
|
## Disciplines (hold in every phase)
|
|
|
|
1. **One fact, one `tht` command.** Every state change goes through a single `tht`
|
|
command (you invoke `tht ...` via the shell tool). NEVER run `tht phase advance`
|
|
or `tht decision add` from the shell — they are blocked by the gate's anti-bypass
|
|
hook; the gate extension records every decision via the `reviewer_*` tools.
|
|
2. **The choice records; the closing gate advances.** A `reviewer_decide`, or a
|
|
`reviewer_select` whose chosen option carries a `decision`, PERSISTS that decision — it
|
|
does NOT by itself advance the phase. In F1, F2-with-memories and F5 the phase closes
|
|
with the deliberate `reviewer_confirm kind:"phase"` summary gate. The `advance:true`
|
|
flag on `reviewer_decide` is a shortcut that auto-advances ONLY F2 when the memory phase
|
|
recorded nothing and F6 when it is skipped/empty; everywhere else it is a silent no-op,
|
|
so never rely on it to advance. The self-closing mechanisms are the five listed above
|
|
(F3 `rewrite_question`, F4 final schema persistence, F6 last
|
|
`kind:"cte_result"`, F7 `kind:"sql"`, F8 `reviewer_memory_promote`) — after one of
|
|
those, do NOT add a `reviewer_confirm kind:"phase"` that merely echoes it; the phase is
|
|
already closed.
|
|
3. **Single pick vs multi-answer.** For a single-pick clarification or decision, use
|
|
`reviewer_select` and attach a `decision` payload (`{type, subject, detail?,
|
|
rationale?}`) to each concrete option: picking it persists that decision directly —
|
|
no follow-up `reviewer_decide`/`reviewer_confirm`. Options WITHOUT a payload only
|
|
ask (use for pure iteration before you commit). For genuinely multi-answer
|
|
decisions (several options simultaneously true) use `reviewer_decide` (multiselect).
|
|
4. **"Accept the proposal" is always an option.** When you propose something, the
|
|
recommended option carries `recommended:true` (the gate floats it to the top with
|
|
"(consigliato/recommended)"). "Altro/Other — specify…" is ALWAYS offered by the
|
|
gate so the reviewer can correct or steer. Never force your recommendation.
|
|
5. **No step in limbo.** Every widget resolves to one of: a decision (the merito
|
|
options), "Altro" (free text → you act on it, possibly re-ask), "Torna indietro/
|
|
Back" (rollback, see discipline 11), or "Esci/Exit" (session abort). If the
|
|
reviewer closes without choosing, the gate re-presents the same widget — there is
|
|
no silent skip.
|
|
6. **Self-contained messages.** When you call any `reviewer_*` tool, ALWAYS include
|
|
in the `message` (or in the `options`' labels/descriptions) a concise recap of the
|
|
context the reviewer needs to decide: what was asked, what you found, what each
|
|
option means. The reviewer does not see your internal reasoning — only the widget.
|
|
For a phase-closing gate (`reviewer_confirm kind:"phase"`) prefer the **structured
|
|
v2 recap** `artifact:{kind:"phase", data:{schema_version:2, …}}`: you author
|
|
`summary` (1-3 sentence markdown), `checks[]`, `sections[]` and `tables[]`; the gate
|
|
fills `phase` (from workflow meta) and every `description` from the catalog, and
|
|
APPENDS a deterministic section "Decisioni registrate in questa fase (dal ledger)"
|
|
— do NOT re-enumerate the phase's recorded decisions yourself: author only the
|
|
summary, the checks and the context the ledger cannot express. Every
|
|
`sections[].items[]` MUST cite the concrete **table**, **column** and the **value**
|
|
that motivates the choice (booleans, time windows, thresholds) — not just prose.
|
|
Compact example:
|
|
```json
|
|
{"schema_version":2,"summary":"Selezionati pazienti attivi con ricoveri nel 2023.",
|
|
"checks":[{"label":"schema_linking valido","status":"ok"}],
|
|
"sections":[{"title":"Criteri di selezione","items":[
|
|
{"label":"solo pazienti attivi","table":"dim_patient","column":"flag_attivo",
|
|
"value":"IS TRUE","kind":"filter","rationale":"esclude i cessati"},
|
|
{"label":"finestra temporale","table":"dim_time","column":"year",
|
|
"value":"= 2023","kind":"filter","rationale":"anno richiesto"}]}],
|
|
"tables":[{"name":"dim_patient","role":"promoted",
|
|
"columns":[{"name":"cod_paz","value_filter":""}]}],
|
|
"open_questions":[]}
|
|
```
|
|
`open_questions` MUST be an array of plain strings (`string[]`). Never put objects
|
|
such as `{label, question}` in it; express each open question as one complete string.
|
|
Legacy free-text recaps still work (no `schema_version`), but prefer v2. Note: the
|
|
F4 schema-linking recap travels in `tables` of this v2 phase payload — do NOT reuse
|
|
`kind:"schema_linking"` for a phase recap.
|
|
7. **Artifact = first-class output.** `schema_linking.json`, `cte_plan.json`,
|
|
`ctes/*.sql`, `sql_final.sql` are produced and reviewed explicitly, never hidden.
|
|
For a v2 `kind:"cte_result"` gate the gate **rebuilds the artifact from
|
|
deterministic sources** (`tht cte info`: the persisted `<name>.sql` + the last CTE
|
|
test record) — you send only the thin `{purpose?, rationale?, note?}` and the
|
|
reviewer approves the gate-built payload, not your text. For final SQL
|
|
(`kind:"sql"`) the gate reads `sql_final.sql` from disk and shows it integral. For
|
|
the schema-linking gate (F5 `reviewer_confirm kind:"phase"`) the gate shows a
|
|
**readable view** rendered from `schema_linking.json`. Write the artifacts with
|
|
care; they are the decision surface.
|
|
8. **Candidates are candidates, not truth.** Present LSH/vector/evidence matches with
|
|
their **provenance** (LSH / vector / evidence) and their scores, never as absolute
|
|
truth. The reviewer may reject them. Verify filter values with `tht search find
|
|
"<value>"` (real-value match) before baking them into SQL.
|
|
{{DISAMBIGUATION_OPEN_AMBIGUITY}}
|
|
10. **Free-text (D13).** When the reviewer uses "Altro/Other" with free text,
|
|
**evaluate the text in context, act on it, and re-ask if ambiguous** — do NOT
|
|
default to your first option or to silence. Record the reviewer's words verbatim
|
|
in the decision `rationale`.
|
|
11. **Rollback (D15).** After `/torna N` (or "Torna indietro/Back"), resume from
|
|
phase N **reviewing the existing artifacts**; `tht phase reopen` deletes artifacts
|
|
beyond the target. Do NOT re-run `tht` commands for artifacts that are still valid.
|
|
12. **This skill is the complete contract.** Every command, flag and behavior you
|
|
need is named in this skill and its reference docs (`rewriting.md`, `cte.md`,
|
|
`sql-generation.md`). Do NOT run `--help`, do NOT read the harness source
|
|
(`tht/`, `.pi/extensions/`, tests) to figure out how a command works, and do NOT
|
|
explore the filesystem with `find`/`grep`/`cat` for that purpose. If something
|
|
genuinely seems missing or a command behaves unexpectedly, say so to the reviewer
|
|
instead of reverse-engineering the tooling.
|
|
|
|
## Phase 0 — Resume (cold start)
|
|
|
|
When launched with `/riprendi-sessione <id>` you have NO prior conversation — the
|
|
persisted state is your only context. Bootstrap before doing anything else:
|
|
|
|
1. `tht session show <id> --json` → read `phase` (the current phase N), `status`, and
|
|
the manifest (`question`, `database`, `schema`).
|
|
2. Load the artifacts produced so far with `tht session documents <id> --json`, which
|
|
returns their keys and contents directly: `question.md` (revised question),
|
|
`schema_linking.json` (F4 output), `ctes/*.sql` + `cte_tests.json` (F6),
|
|
`sql_final.sql` (F7). The decision ledger is summarized by `tht session show`.
|
|
**Non cercare i file fisici con `find`, `ls`, `cat` o il generic read tool**: the
|
|
session repository may live outside the checkout and the documents command is the
|
|
canonical read boundary.
|
|
3. **Resume at phase N reviewing the existing artifacts** (same discipline as rollback,
|
|
§Disciplines 11). Do NOT restart from Phase 1, do NOT re-run `tht` commands for
|
|
artifacts that already exist and are valid, and do NOT treat this as a new question.
|
|
4. Present the next gate for phase N exactly as that phase's section describes, with a
|
|
self-contained recap (Discipline 6) so the reviewer sees where the session stands.
|
|
|
|
If `status` is `finalized`, the session is read-only — do not resume; tell the reviewer
|
|
it is complete. (The backend already refuses resume for finalized/archived sessions.)
|
|
|
|
{{EVIDENCE_RUNTIME_SEARCH}}
|
|
|
|
{{DISAMBIGUATION_INSTRUCTIONS}}
|
|
|
|
{{MEMORY_INSTRUCTIONS}}
|
|
|
|
{{DISAMBIGUATION_REWRITING_INSTRUCTIONS}}
|
|
|
|
## Phase 4 — Schema linking
|
|
|
|
Prerequisite: Phase 3 closed.
|
|
|
|
1. `tht schema render --format mschema-text` for the schema context (the catalog
|
|
`artifacts/mschema/physical.yaml` is already in the workspace; only if render fails
|
|
with `physical.yaml non trovato`, run `tht schema introspect` once, then render).
|
|
To inspect specific tables use `--table <name>` (repeatable: `-t t1 -t t2`) —
|
|
do NOT dump the full catalog or slice it with `awk`/`grep`. The session's
|
|
`retrieval_pack.md` (built in F1) already lists the candidate tables for the
|
|
question — start from those.
|
|
Copy table/column names EXACTLY from it — never invent objects.
|
|
{{MEMORY_SOLVED_SEARCH_F4}}
|
|
2. Propose tables to promote/exclude with **`reviewer_schema_linking`**: pass
|
|
`tables[]` as `{id, name, kind: "promote"|"exclude", rationale, suggested_columns}`.
|
|
Do NOT list every column yourself — the gate loads the full column set (with
|
|
descriptions) from the catalog and pre-selects your `suggested_columns`. The
|
|
reviewer curates the columns per promoted table. The tool records
|
|
`table_promoted`/`table_excluded` + `column_promoted`/`column_excluded` and
|
|
re-projects `schema_linking.json` deterministically via `tht session
|
|
sync-schema-linking` (you do NOT hand-write the tables/columns part with
|
|
`write_schema_linking`). The promoted columns are the reviewer-approved OUTPUT
|
|
columns: project exactly those in the final SELECT (Phase 6/7); you remain free
|
|
to reference other columns as join keys or filter predicates when the query
|
|
requires them.
|
|
Call `reviewer_schema_linking` before the join review. For a multi-table plan,
|
|
`advance:true` will report that F4 remains open because the structured joins are
|
|
not present yet; this is expected. Stay in F4 and continue with the join-only gate.
|
|
Propose **all required joins together in a separate, join-only**
|
|
`reviewer_decide(advance:false)`, registering `join_modified`. Do not mix
|
|
`join_modified` with other decision types in that call. The gate renders this proposal
|
|
as read-only information: **Continue records every proposed join**; the reviewer cannot
|
|
remove individual joins (which could create an accidental Cartesian product). The complete
|
|
set is persisted atomically under a per-session writer lock: an invalid response or write
|
|
failure records none of it. If the reviewer uses **Other — specify**, none of the current
|
|
joins is recorded: incorporate the textual correction and present the complete revised join
|
|
set again.
|
|
Ground joins in the `【Foreign keys】` section of the mschema-text
|
|
render: it lists the curated logical FKs of the workspace (e.g.
|
|
`fact_x.cod_paz=dim_patient.cod_paz`, `*_time_key=dim_time.day_key`) — prefer
|
|
those to joins you derive yourself, and flag to the reviewer any join you need
|
|
that is NOT in the list.
|
|
{{DISAMBIGUATION_SCHEMA_GROUNDING}}
|
|
{{EVIDENCE_FORMULA_PROPOSALS}}
|
|
5. Persist the **joins** (and any `concept_formulas`/`open_questions`) with the gate's
|
|
`write_schema_linking` tool — it validates the object against the `SchemaLinking`
|
|
model and writes the file deterministically (never hand-write it, never edit it
|
|
with the file tool; on a validation error the tool returns the exact problem to
|
|
fix). Shape: `{question, candidates:[...], joins:[{from, to, source?}],
|
|
excluded:[...], open_questions:[], concept_formulas:[]}` — `candidates`/`excluded`
|
|
are owned by `reviewer_schema_linking`/`sync-schema-linking` (step 2), so if you
|
|
call `write_schema_linking` after step 2, carry over its `candidates`/`excluded`
|
|
unchanged rather than overwriting them. After the reviewer-approved joins are present,
|
|
`write_schema_linking` closes F4 automatically. Do not add a `reviewer_confirm
|
|
kind:"phase"`. Do NOT run `tht session check` (that's Phase 5).
|
|
|
|
## Phase 5 — Synthesis
|
|
|
|
Prerequisite: Phase 4 closed; `schema_linking.json` present.
|
|
|
|
1. `tht session check` (objective gate: decisions present + schema_linking valid).
|
|
2. Summarize the schema-linking to the reviewer; if corrections are needed, reopen
|
|
Phase 4.
|
|
3. Close with `reviewer_confirm kind:"phase"`.
|
|
|
|
## Phase 6 — CTE plan
|
|
|
|
Prerequisite: Phase 5 closed.
|
|
|
|
1. Read `cte.md`. Decompose the rewritten question into CTEs (Agent View Generation):
|
|
each CTE captures an informative subset with a clear purpose, named in snake_case.
|
|
{{MEMORY_SOLVED_SEARCH_F6}}
|
|
2. Present the full CTE plan to the reviewer with `reviewer_confirm kind:"cte_plan"`,
|
|
passing a **structured v2 artifact** (`artifact:{kind:"cte_plan", data:{…}}`). You
|
|
author `question`, `strategy` and each `ctes[]` entry (`name`, `purpose`,
|
|
`rationale`, `depends_on`, `tables[].name`, `keys`, `filters[]` with
|
|
`column`/`op`/`value`/`rationale`, `output_columns`); the gate fills `index`
|
|
(1-based) and every `description` from the catalog, derives the ordered `--name`
|
|
list from `data.ctes[].name`, and on approval persists both `cte_plan.json` and the
|
|
chain doc (`cte_plan_doc.json`). Compact example (2 CTE):
|
|
```json
|
|
{"schema_version":2,"question":"pazienti attivi con almeno un ricovero nel 2023",
|
|
"strategy":"prima la base dei pazienti attivi, poi i loro ricoveri filtrati per anno",
|
|
"ctes":[
|
|
{"name":"base_pazienti","purpose":"pazienti attivi","rationale":"insieme di partenza",
|
|
"depends_on":[],"tables":[{"name":"dim_patient"}],"keys":["cod_paz"],
|
|
"filters":[{"column":"dim_patient.flag_attivo","op":"IS","value":"TRUE","rationale":"solo attivi"}],
|
|
"output_columns":["cod_paz"]},
|
|
{"name":"ricoveri_2023","purpose":"ricoveri dei pazienti nel 2023","rationale":"restringe al 2023",
|
|
"depends_on":["base_pazienti"],"tables":[{"name":"fact_ricoveri"}],"keys":["cod_paz"],
|
|
"filters":[{"column":"dim_time.year","op":"=","value":"2023","rationale":"finestra temporale"}],
|
|
"output_columns":["cod_paz","data_ricovero"]}
|
|
]}
|
|
```
|
|
3. For each CTE (in plan order): call `write_cte_sql` with the session id, CTE name,
|
|
and SQL block (the tool invokes `tht cte save --session <id> --name <name> --file -`).
|
|
Persist ONLY the
|
|
`WITH ... AS (...)` block, NO trailing SELECT), test with `tht cte test --session
|
|
<id> <name>` (with an **ok** outcome), then present it with
|
|
`reviewer_confirm kind:"cte_result"`. Pass ONLY the thin v2 data
|
|
`artifact:{kind:"cte_result", data:{schema_version:2, purpose?, rationale?, note?}}` —
|
|
NEVER paste SQL, columns or preview rows as text: the gate reads them
|
|
deterministically from `tht cte info` (the persisted `<name>.sql` + the last test
|
|
record) and builds the full artifact the reviewer approves. The next CTE is testable
|
|
ONLY after the previous one is approved (CLI exit 5 if out of order). Copy
|
|
table/column names EXACTLY from the schema context; use values verified with
|
|
`tht search`.
|
|
4. After the last CTE is approved, close with `reviewer_confirm kind:"phase"`.
|
|
|
|
## Phase 7 — Final SQL
|
|
|
|
Prerequisite: Phase 6 closed.
|
|
|
|
1. Read `sql-generation.md`. Recursive divide-and-conquer: the CTEs approved in
|
|
Phase 6 are the preferred building blocks (reuse them by name).
|
|
{{MEMORY_SOLVED_SEARCH_F7}}
|
|
2. Compose the final SQL (PostgreSQL dialect, exact names from the schema context).
|
|
**Output columns (F4 honoring).** The columns promoted in Phase 4's
|
|
`schema_linking.json` are the reviewer-approved OUTPUT columns: project exactly
|
|
those in the final SELECT. Other schema-linked columns remain usable as join
|
|
keys or filter predicates, but do not add them to the SELECT list.
|
|
**Time dimension:** `data_time_key` is the FK to `dim_time.day_key` (NOT declared
|
|
in the DWH, must be added by hand to the join); use `JOIN dim_time` and its
|
|
columns (`dt.year`, `dt.month`, …), NEVER arithmetic on the key.
|
|
3. `tht sql validate` + `tht sql preview` (max 10 rows). On errors / suspicious
|
|
results, apply the `sql-generation.md` checklist and correct with the reviewer.
|
|
4. Call `write_final_sql` with the session id and clean SQL; it invokes
|
|
`tht sql set-final --session <id> --file -` (ONLY clean SQL, no comments).
|
|
Approve with `reviewer_confirm kind:"sql"` (records `sql_approved`), then advance to
|
|
Phase 8 with `reviewer_confirm kind:"phase"` — `kind:"sql"` alone does NOT advance F7.
|
|
|
|
## Phase 8 — Datamart
|
|
|
|
Prerequisite: Phase 7 closed.
|
|
|
|
1. Call `reviewer_datamart` with the session id. This gate is deployment-aware and is
|
|
the ONLY allowed way to record the datamart choice:
|
|
- `THT_PROFILE=workstation`: it records `datamart_declined` automatically and shows
|
|
no question to the reviewer;
|
|
- `THT_PROFILE=server` (including the default): it always shows both choices,
|
|
"Sì, genera il datamart" and "No, salta il datamart", and records the selected one.
|
|
Never replace this gate with a hand-built `reviewer_select`.
|
|
2. On a server, if the reviewer chose yes: `tht datamart generate` (stub — raises
|
|
NotImplementedError for now). Tell
|
|
the reviewer that dbt generation is not implemented yet.
|
|
{{MEMORY_PROMOTION_F8}}
|
|
|
|
## Session end
|
|
|
|
When the promotion gate (or, as fallback, the F8 phase gate) closes Phase 8, the
|
|
gate calls `tht session finalize` automatically.
|
|
{{MEMORY_SOLVED_FINALIZATION}}
|
|
state (ledger `review_decisions.jsonl` + artifacts) is the truth: what is not
|
|
recorded did not happen.
|