--- name: session-reflection description: Use when the user asks to reflect on a session or to compact it -- "reflexionemos sobre la sesión", "cerremos esto", "guardemos lo que aprendimos", "compactemos", "compacta", "let's reflect on this session", "wrap up this session", "compact the session" -- or when closing substantial work: the orchestrator reconciles the session against memory and the coordination substrate (briefs/plans/tasks/approvals), curates and closes what it can decide on its own, reports what changed, and when asked to compact, records the resume point and starts the compaction. --- # Session Reflection Session reflection is everything the session lived, contrasted against what belongs to each project, until no loop is left dangling. It recovers the whole arc, reconciles it against the durable corpus in both directions, and leaves every item — settled or open — with an owner a later session can find. Upstream are the transcript, the specialist contracts, and the injected digest. Downstream is memory curation: reflection ends when the corpus is correct. When the user asks to compact, compaction is the reflection's last step, never a step of its own: a compaction that skips the reflection loses whatever had no home yet. ## Process 1. **Recover the whole arc.** Scan from the session opening for accepted and rejected proposals, deferrals, closures, user corrections, and specialist reactions — recency is not weight, an early settled choice still stands. Include `cross_layer_impacts`, `open_gaps`, and `failure_report` findings even where the user never reacted: they are observations about Gaia, not conversational agreements. `reference.md` holds the full recovery pass. 2. **Reconcile in both directions.** For each initiative the session touched, read its live corpus — `gaia memory get-relevant --initiative=` returns that whole pending set uncapped, with bodies — and ask: what did this session produce with no home yet, and what already-open pending did it close, advance, or invalidate? A topic search only answers whether your own phrasing has a row; the closure you owe is usually phrased in terms that predate the session that solved it. Read briefs, plans, tasks, and approvals the same way — a conversation cannot close an object the substrate still shows open. A session that produced any Gaia improvement touched `gaia_system` by definition, whatever project it was nominally working on — sweep it too. `reference.md` holds the reverse-sweep mechanics and the objective-state checks that verify a `SKIP`. 3. **Classify disjointly.** Separate settled decisions and learnings, genuinely open work, and Gaia improvements. When closure is uncertain, classify as open; a lost pending costs more than an extra review. For anything about Gaia itself, `memory/SKILL.md`'s ownership test decides the initiative — `gaia_system` for an observed failure or friction, project-scoped `gaia` for a decision to build or change something. 4. **Give every item a home, and know what the home does.** The pending worklist that returns to the user each session selects `class=thread` with status `carry_forward` or `open` only — an `anchor` still reaches a dispatched agent as held knowledge, but never comes back as work. Filing live work as an anchor hides it; filing settled knowledge as a thread turns the worklist into noise. `SKIP` is a home only when you name the canonical object that owns the item — already-canonical work is referenced, never copied. 5. **Adjudicate against the exception boundary.** The boundary table lives in `memory/SKILL.md` ("Process" step 5) — this is a pointer to it, not a copy. Most operations are decided and executed directly; only the rows the boundary marks "ask first" or "veto" wait on the user. 6. **Run the curation, closures included.** Materialize the step 2 closures alongside the new rows; `reclassify` and `append` are non-mutative, so nothing but omission keeps a resolved thread open. A closing arc that passes the milestone test in `reference.md` uses `checkpoint`, one atomic write; an ordinary close does not. 7. **State the resume point.** One line naming what the next session picks up — a pointer, not a container: everything it names already has a row. ## Working tables These internal tables force one owner per item before curation; omit empty sections. `SAVE`, `APPEND`, `TRANSITION`, `LINK`, and `SKIP` are adjudicated by `memory`; a closure or graduation is a `TRANSITION` materialized as `reclassify`. `memory/reference.md` owns the exact forms. ### What we settled Accepted decisions, closures, and reusable learnings. Prefer `SKIP` naming the canonical object; `SAVE` only knowledge that must constrain a later choice. | Item | Home | Operation | |---|---|---| | the decision, in the user's words | slug, commit, or brief/plan/task id | SAVE, APPEND, LINK, or SKIP | ### Open work One row per unresolved concern and per pending the sweep found resolved; the latter is a `TRANSITION`, never a silent omission. | Item | Home | Operation | |---|---|---| | the concern, in the user's words | slug, brief/plan/task id, or initiative | SAVE, APPEND, TRANSITION, LINK, or SKIP | ### What Gaia should improve Symptom observable behavior, not diagnosis Component one precise owner Evidence observed proof Reproduction exact repeatable route, or unknown → feedback__ · type feedback · SAVE or APPEND Work the evidence through before saving; `reference.md` owns field definitions and the `gaia_system` retrieval query. ## Output The user sees a post-curation report, one line per durable effect, not the working tables or raw verbs. Flag a `type=user` row first for its governed veto. ### Resume point Name what the next session picks up: a pointer, never a copied container. ## Compacting After step 7, when the user asked to compact. The session id is the `- Session id:` line of the `## Environment` block, which arrives at birth and after every compaction on both hosts. 1. **Request the compaction.** Call the host's compaction tool once: `mcp__gaia__compact_when_idle` in Claude Code, `gaia_compact_when_idle` in OpenCode. It schedules the compaction for when the current turn ends, never mid-turn. The host can still refuse it. 2. **Write the resume point.** `gaia session resume-point set --session-id --text ""`, at most 2000 characters, replacing any earlier one: the step 7 pointer plus what the next turn needs and no row holds -- the exact next action, blockers and approvals in flight, the active files. Durable objects are named by id, never copied. 3. **End the turn** with the post-curation report and a line saying the compaction was requested -- not that it will happen. The snapshot that arrives after compaction carries the resume point; do not restate either in the turn. If the next turn carries a note that the compaction did not start, tell the user so, name the host's reason, and ask them to type `/compact`. When the user insists on compacting before the reflection finishes, offer it once; if they decline, write the unsaved items into the resume point marked as not durable, rather than dropping them or saving memory unasked. **Without the tool** -- a headless Claude Code session (the desktop app, `-p`, the SDK), where the host cannot compact from a mod, Claude Code with mods disabled or older than 2.1.287, or any host that does not list it -- nothing the orchestrator runs can start the compaction. Skip step 1, still write the resume point (step 2) with the Environment block's session id, and end the turn asking the user to type `/compact`: the report itself is summarized away, the resume point survives into the snapshot. Never report a compaction you did not start. When the user types `/compact` without asking to compact first, nothing above runs: the snapshot carries the last resume point written, however old, or none. ## Ownership and consent Consent mechanics belong to `memory`: the orchestrator recovers, reconciles, and adjudicates, while `gaia-operator` materializes exact instructions. Any operation requiring consent is delegated through its approval flow and never autoexecuted. Independent operations are best-effort; a checkpoint stays atomic, so partial state is never reported as closure. Reflection itself is not a new durable object. ## Handoffs - Load `memory` for curation and `reference.md` for detailed recovery mechanics. - Load `examples.md` for the integrated flow, compaction included.