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).