refactor(pi): generate modular session instructions (#25)

2026-08-24 01:36:08 +02:00
parent 4a654de84a
commit eccf6212f1
15 changed files with 606 additions and 0 deletions
@@ -0,0 +1,36 @@
+## Phase 2 — Memories
+
+Prerequisite: Phase 1 closed.
+
+1. Search reusable memories: `tht memory search "<question>" --session <id> --json`.
+   **ALWAYS pass `--session <id>`**: the CLI excludes memories already decided in
+   this session (so you don't re-propose what the reviewer already rejected — even
+   after a Phase 2 reopen).
+2. The hit comes with full metadata (subject/detail/rationale): read what it says,
+   where it comes from, why it might apply here, the out-of-context risk.
+3. Present candidates in **a single** `reviewer_decide(multi:true, advance:true,
+   allow_empty:true)`. Rules: at most **5** candidates; ONLY
+   `concept_clarified`. Table choices (`table_promoted`, `table_excluded`) and all
+   other query-specific decisions (`question_rewritten`, `sql_approved`, …) are NOT
+   transferable and must never be stored, retrieved, or proposed as memories. Each
+   option carries `type`/`subject`/`rationale`; cite the source
+   memory id (`mem-<id>`) in its rationale when applying it. Copy the hit's full
+   `content` verbatim into the option `description`: the reviewer must see the exact
+   memory text before deciding. Deduplicate hits by memory id before calling the gate.
+   Every option describes a
+   candidate memory; never create an opposite "do not use" option. Only
+   `recommended:true` options start checked. A
+   deselected candidate is **not applied now**, not rejected, and may be considered
+   again if Phase 2 is reopened. With `allow_empty:true` an empty selection is accepted
+   (no memory applied) and the phase advances — no separate gate.
+   When the memory search returned **zero** candidates, still issue the single
+   `reviewer_decide(multi:true, advance:true, allow_empty:true)` with an empty merito list: the gate
+   detects the empty+advance case, shows the reviewer an info notice ("Nessuna memory
+   riutilizzabile … passo alla fase successiva") and auto-advances F2 — it does NOT present
+   an empty checklist, and you do NOT add a separate `reviewer_confirm kind:"phase"`.
+4. Closing: if one or more memories were applied (substantive decisions), `advance:true`
+   no-ops — close with `reviewer_confirm kind:"phase"`. If none is applied, F2
+   auto-advances via `advance:true`.
+5. Memories are promoted at the END of the workflow (Phase 8, the
+   `reviewer_memory_promote` gate) — never promote from here, never run
+   `tht memory promote`/`save-one` yourself (the gate blocks them).
@@ -0,0 +1,13 @@
+3. **Memory promotion closes the session.** Call `reviewer_memory_promote` with ONLY
+   the session id: the gate computes the candidates itself (`tht memory promote
+   --preview` — the 3 reusable types, already excluding promoted/declined ones) and
+   shows the reviewer a pre-selected checklist. Selected → saved to the vectordb +
+   `memory_promoted`; deselected → `memory_promotion_declined` (never re-proposed).
+   After recording the promotion (even with zero candidates) the gate advances F8 and
+   finalizes the session itself — do NOT present a `reviewer_confirm kind:"phase"`
+   afterwards: there is nothing left to approve. When the gate answers "sessione
+   finalizzata", give the reviewer the final summary and end the turn.
+4. If the gate reports an error instead (e.g. the datamart decision is missing),
+   fix the prerequisite and call `reviewer_memory_promote` again. Only if the gate
+   says the session is still open, close with `reviewer_confirm kind:"phase"` as a
+   fallback — it auto-finalizes after advancing the last phase too.
@@ -0,0 +1,2 @@
+Finalize also indexes the question→SQL pair in the vectordb (kind `solved_question`,
+best-effort — on failure recover with `tht memory solved-index <id>`). The persisted
@@ -0,0 +1,4 @@
+   Also run `tht memory solved-search "<question>" --json`: similar already-solved
+   questions show which tables comparable questions used. Cite relevant precedents
+   (session id + tables) to the reviewer as CONTEXT — they are reference material,
+   NOT decisions to apply; their filters/periods may not transfer.
@@ -0,0 +1,2 @@
+   `tht memory solved-search "<question>" --json` shows how similar solved questions
+   were structured — use as reference only.
@@ -0,0 +1,3 @@
+   `tht memory solved-search "<question>" --json` gives the final SQL of similar
+   solved questions: reference exemplars — never copy filters, periods or
+   populations without checking them against the current rewritten question.