recall/learn/write-memory: promote runbook conversion from eval fixture to real production skill replacement

[toejough]

Follow-on to runbook-shim-follow-frame (archived: openspec/changes/archive/2026-09-17-runbook-shim-follow-frame/). Found while splitting #756 (closed) into per-skill tickets — this is a 4th, distinct piece of missing follow-on work, not covered by #756 or by the route/please/curate tickets, and easy to lose if not filed on its own.

The gap

The archived change's tasks 3.1/3.2/3.4 converted recall, learn, and write-memory from SKILL.md bodies into runbook notes — but only as eval fixtures, for the shim-only comparison harness. Confirmed by direct inspection of this worktree:

• The real, deployed skills are unchanged and still live as skills: agent-instructions/skills/recall/SKILL.md, agent-instructions/skills/learn/SKILL.md, agent-instructions/skills/write-memory/SKILL.md all still exist, still author-format as skills, still what real sessions install.
• The runbook conversions only exist under the eval tree: dev/eval/cumulative/runbook_vs_skill/phase2/encodings/shim/recall-learn/vault/ (8 runbook notes: recall glance-vs-deep-mode, note-synthesis-and-coverage, activation-and-closing-synthesis, learn crystallize-lesson-kinds, qa-capture-and-reparent-batch, recall-from-unified-memory, learn-sweep-and-crystallize, write-memory-compose-execute-verify).
• The production guidance files agent-instructions/guidance/recall.md, delegate.md, learn.md are also unchanged — design.md's D0 explicitly deferred this: "recall.md/delegate.md/learn.md stay as they are for sessions that still install the skills; reconciliation belongs to the later recall-replacement effort" — and D2 separately noted "Replacing the deep recall procedure (ten phrases, clustering, coverage judgment, crystallization) with the shim is a separate, larger effort."

So today, production sessions still install and run the recall/learn/write-memory skills with the original recall.md/learn.md/delegate.md guidance — the validated shim + runbook path only exists inside the eval sandbox. Joe's stated ultimate goal (proposal.md's Why: "every skill, including recall and learn, become a runbook, with one CLAUDE.md shim as the only custom instruction text") is not yet realized for real sessions, even though it is now validated on 2 of 3 real procedures for other runbooks (history-rewrite, bisect-before-fix).

Scope of this ticket

• Promote the eval-fixture runbook bodies at dev/eval/cumulative/runbook_vs_skill/phase2/encodings/shim/recall-learn/vault/ into the real vault/skill-replacement location (mirroring wherever the route/please/curate conversions land, once those tickets settle a convention).
• Retire agent-instructions/skills/{recall,learn,write-memory}/SKILL.md.
• Reconcile agent-instructions/guidance/{recall,delegate,learn}.md with agent-instructions/guidance/shim.md for real deployment — decide whether shim.md fully replaces them for production sessions or whether some hybrid is needed (design.md D0/D2 explicitly left this open as "the later recall-replacement effort").
• Handle the fact that recall.md names /recall glance, which has no equivalent in a shim-only session (design.md's Impact section names this reconciliation as open) — a production reconciliation needs to resolve this, not just the eval config.
• Re-validate deployment: engram update --with-guidance currently syncs shim.md alongside the existing guidance files (task 2.4); confirm what the sync should look like once shim.md is meant to be the sole production guidance rather than an additional file.

Cross-references

• Archived change: openspec/changes/archive/2026-09-17-runbook-shim-follow-frame/ (design.md Context, D0, D2; proposal.md Why/Impact)
• Closed parent: Convert route, please, and curate skills to runbooks (follow-on to runbook-shim-follow-frame) #756
• Sibling tickets: to be linked once filed (this ticket is a superset concern that likely wants to land after route/please/curate settle a runbook-deployment convention, but is independently scoped and trackable now)

[toejough]

Sibling tickets (found while splitting #756): #757 (route), #758 (please), #759 (curate).

[toejough]

Partial resolution: activation/reconciliation decision made, promotion still open

While closing out #757, needed shim.md actually active in production for route's SKILL.md retirement to be safe (a D8 pass inside the eval's shim-only fixture doesn't prove any real session would discover the runbook). That's this ticket's own listed scope item ("decide whether shim.md fully replaces them, or hybrid needed"), so resolving just that slice here rather than leaving it implicit.

Decision: hybrid, not full replace. shim.md (112 lines) carries only the runbook-following frame — it has none of recall.md's 10-phrase/clustering/coverage-judgment procedure, learn.md's four-kind crystallization scan, or delegate.md's orchestration-routing doctrine. Full replacement isn't available until this ticket's remaining scope (promoting recall/learn/write-memory to runbooks) actually happens. shim.md is now added alongside the other three in both ~/.claude/CLAUDE.md and ~/.pi/agent/AGENTS.md, not replacing them — its runbook-following frame is active for any kind: runbook note (route's, now), while the other three continue covering everything else.

Tracked as its own change, activate-shim-guidance (checked for requirement-collisions against the other active changes first, per this repo's own convention).

Noted, not fixed here: a real but non-blocking redundancy — shim.md's bootstrap-query instruction substantially overlaps recall.md's own firing-moment cues. Worth a look whenever the promotion work below actually happens.

Still open (this ticket's remaining scope): promote recall/learn/write-memory's eval-fixture runbook bodies to production, retire their SKILL.md files, resolve the /recall glance naming gap for shim-only sessions, and re-validate engram update --with-guidance's sync behavior once shim.md is the sole production guidance (if it ever is). Route's own retirement (#757) is now a real, working precedent for the retire-SKILL.md step once these three are ready.

[toejough]

Update 2026-09-25: re-scoping this ticket rather than closing it.

Regression. engram update only deploys files under agent-instructions/skills/ and guidance/. It never distributes vault notes. Deleting the SKILL.md and keeping the procedure only as a note in the maintainer's vault meant fresh installs stopped getting this skill — after the four conversions, only learn and recall shipped. The conversion proposals listed "engram update stops shipping the directory" under Impact as if it were neutral. Vault note 1054 records the reversal.

Pivot. Skills are the shipping form again. Each skill may also have one companion vault runbook note (slug skill-<name>, frontmatter skill_hash) that mirrors the skill text and carries situation/triggers/done_when/red_flags, so memory surfacing, the shim follow-frame, and cross-vault sharing keep working. engram update and the new engram register-skills command offer to register, refresh, or remove these notes; the user decides, and a declined offer is remembered by hash so it isn't repeated.

What changes for this ticket:

• write-memory: its skill retirement (a81f7edc) is reversed. agent-instructions/skills/write-memory/SKILL.md is restored from cbda7f6e, and recall/learn invoke it natively as a skill again at all nine write sites (the eval's skill-arm baseline was 3/3 on both metrics that way). Note 1053 becomes its companion note via --adopt.
• recall / learn: they will not be converted to replace their skills. The two in-flight changes that would have done that (learn-skill-to-runbook, recall-glance-skill-to-runbook) are abandoned before any paid run; their fixture vaults and fidelity reports stay under dev/eval/.

Remaining scope here: register recall and learn through the offer flow and author their companion notes' runbook fields from those fixture runbooks, then run the no-spend retrieval checks (tasks 4.1–4.5 of register-skills-as-runbooks). recall keeps its glance/deep modes as a skill; only splitting it into two runbook notes is dropped. Reconciling guidance/{recall,learn,delegate}.md with shim.md stays a separate follow-on.

Status: implemented on local main in OpenSpec change register-skills-as-runbooks (lands with the next push). The vault adoption step still has to run on the maintainer's machine.

[toejough]

Status 2026-09-26: the re-scoped work is done. This ticket stays open until #767 merges and closes then. The guidance reconciliation has moved to #773.

The original premise has been reversed. The body asks to retire agent-instructions/skills/{recall,learn,write-memory}/SKILL.md and make shim.md the only production guidance. That will not happen:

• Vault note 1054 refutes note 1031's goal that every skill becomes a runbook. Deleting a SKILL.md stopped the procedure from shipping, because engram update syncs skills and guidance but never syncs vault notes.
• 21d6c603, now on origin/main, restored route, please, curate and write-memory. The write-memory retirement (a81f7edc) is undone, and on origin/main recall and learn invoke write-memory as a skill again.

The re-scoped work (tasks 4.1–4.5 of register-skills-as-runbooks) is done on branch worktree-runbook-vs-skill, in openspec/changes/archive/2026-09-26-register-skills-as-runbooks/, where all 35 tasks are ticked:

• recall and learn were registered through the offer flow and now have vault notes 1068.2026-09-26.skill-recall and 1067.2026-09-26.skill-learn. Their runbook fields come from the fixture runbooks and were checked by a fresh-context review.
• The no-spend retrieval checks are recorded in dev/eval/cumulative/runbook_vs_skill/phase2/results/5.1_register_skills_recall_learn_curation_and_retrieval.md.
• The skills are deployed on the maintainer machine: all six are in ~/.claude/engram/skills/, each has a skill-<name> note (1036, 1045, 1049, 1053, 1067, 1068), and engram register-skills --dry-run reports no pending offers.

Why this stays open: the archive and the code are only on the branch, and #767 tracks their review, rebase and ff-merge. When #767 merges, close this ticket as completed.

Moved to #773: reconciling guidance/{recall,delegate,learn}.md with shim.md. The two files give the same four decision moments different actions (/recall glance vs engram query), and shim.md's header still describes a "shim-only session". That item was a follow-on outside register-skills-as-runbooks' scope, so it gets its own ticket instead of holding this one open. The /recall glance gap was specific to shim-only sessions and is moot now that the recall skill ships everywhere. Widening registration to every default skill folder, including project-local .claude/skills/, is tracked by the pending change openspec/changes/register-skills-all-skill-folders/.

No blocked label was added because this repo doesn't define one.

[toejough]

Done: the registration work (register-skills-as-runbooks, then register-skills-all-skill-folders, both archived) is on main as of e1930b5 via #767. Remaining guidance reconciliation is tracked in #773.