reflect · diff
git:20260821.646162c to git:20260903.43760e1
53 added, 17 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: reflect
- description: Ask Mubit to extract lessons from this session's activity and report what it learned. Use when a long session has just finished a real chunk of work, or before a compaction, to bank what was learned while the evidence is still indexed.
+ description: Ask Mubit to extract lessons from this session's activity and report what it learned. Use when the user wants lessons banked now rather than at session end, or asks what memory holds for this project.
---
- Reflect over the current run with `mcp__mubit__mubit_reflect` — `POST /v2/control/reflect
- {run_id}` — and report the extracted `lessons[]` back to the user: `lesson_id`,
- `lesson_type`, and `scope` for each, one line apiece. If the response is empty, say so
- plainly; an empty reflect is a real answer, not an error. Use `mcp__mubit__mubit_lessons`
- afterwards when the user wants to see what is now visible at `global` scope rather than what
- this run just produced.
+ ## Step 0 — resolve the binary
+ No environment variable carries this plugin's path under Codex. Codex lists each skill with the
+ absolute path of its `SKILL.md`; **this file** is at `<plugin-root>/skills/reflect/SKILL.md`, so
+ the binary is two directories above it:
+
+ ```
+ <plugin-root>/bin/admin.mjs
+ ```
+
+ Resolve that to an absolute path from this file's own location and use it in every command
+ below. Do not write `${CLAUDE_PLUGIN_ROOT}`: Codex sets no plugin-root variable of any
+ spelling, so the shell expands it to nothing and `node /bin/admin.mjs` fails with ENOENT.
+
+ Reflect over the current run with the bundled script — `POST /v2/control/reflect {run_id}`
+ behind it — and relay what it prints: one line per extracted lesson, with the lesson's id,
+ type, importance and scope on the line.
+
+ ```bash
+ node <plugin-root>/bin/admin.mjs reflect
+ ```
+
+ If it reports no lessons, say so plainly; an empty reflect is a real answer, not an error.
+ Neither command here is an MCP tool: `mubit_reflect` and `mubit_lessons` left the default
+ tool surface so that a session pays nothing to list them, and this script reaches the same
+ two routes.
+
+ ## The standing catalogue
+
+ When the user wants what memory holds rather than what this run just produced:
+
+ ```bash
+ node <plugin-root>/bin/admin.mjs lessons # this run, plus what travelled
+ node <plugin-root>/bin/admin.mjs lessons --scope run # this run alone
+ node <plugin-root>/bin/admin.mjs lessons --scope global # only what has travelled
+ node <plugin-root>/bin/admin.mjs lessons --importance high --limit 10
+ ```
+
+ The three scopes answer three different questions, and asking the wrong one is how a healthy
+ store reads as empty:
+
+ - **no `--scope`** — this run's lessons, plus every lesson stored above `run` scope by any
+ run. The honest default, and the right one for "what do we know here".
+ - **`--scope run`** — this run alone. What this session has banked so far.
+ - **`--scope session` / `global`** — only the lessons that have travelled, from every run
+ the key can see. Read a zero here as a real zero rather than as a fault.
+
+ The listing says what it is showing and how many matched. A lesson this conversation has
+ already been shown is printed as its id and first clause, marked `(seen earlier)`;
+ `mcp__mubit__mubit_dereference` returns the text. `--json` is the whole catalogue with its metadata.
+
## Why the explicit call exists at all
Mubit already extracts lessons on its own, in the background, as it ingests. It does that
perfectly well — and then stops there. Lessons extracted that way keep the scope they were
extracted at, typically `run`, and **a `run`-scoped lesson is invisible to the next session**.
The consequence is concrete: the store can look busy, lessons accumulating steadily, while
nothing ever crosses the boundary into a future session. Widening a lesson's scope is
reserved for the explicit reflect path — this skill, and the one `SessionEnd` issues.
Widening is still gradual once a lesson is on that path. Rules are never scope-promoted, since
they are enforced as written; anything else has to establish itself before it travels. Expect
lessons to widen over several sessions, not on the first reflect.
## When to invoke it
- The `SessionEnd` hook already reflects once per session, on the way out, with the same run id.
+ `session-end.mjs` already reflects once per session, on the way out, with the same run id.
That covers routine hygiene. Invoke this skill for a **mid-session checkpoint** — a long
session that has just finished a real chunk of work, a debugging arc that ended in something
worth keeping, or the point where the user is about to compact and wants the lessons banked
first. Do not call it every few turns: it is an LLM-backed extraction pass over the run, and
calling it on a run that has barely changed costs time and returns the same lessons.
- There is one Codex-specific reason to reach for it more readily than you would under Claude
- Code. Codex clamps a `SessionEnd` hook to **three seconds** and kills it there. The plugin
- hands the end-of-session flush to a detached process precisely so the reflect survives that,
- but a detached child can still be reaped with the terminal — a container exiting, a machine
- sleeping — and when it is, that session's reflection is simply lost. A mid-session reflect is
- the only thing that banks the lessons before that window. `mubit-memory:doctor` reports
- `reflect.status` if you want to know whether the last session's flush actually landed.
-
One timing detail worth knowing before you read a zero as a failure: reflection only sees
items the server has already **indexed**. A reflect fired immediately after a burst of
- captures or an explicit `mubit-memory:remember` can honestly return `lessons_stored: 0`
+ captures or an explicit `mubit-memory:remember` can honestly report `lessons_stored: 0`
where the same run reflected about a minute later returns them. If you have just written
something you expect to be reflected on, give ingest a moment rather than reflecting twice.