/memory-sync

name: memory-sync
description: >
  Persist new context, terms, learnings, and settled lightweight decisions. Use when
  the user says remember this, save this for later, add to glossary, note this down,
  or at session end to consolidate what was learned — that goes to the memory layer
  (CLAUDE.md hot cache, docs/memory/, docs/inbox.md). Also use to record a decision
  or remember this decision when the call is a lightweight one shipped outside a
  spec slice: UI strings, visual and CSS choices, copy, or translation fixes. Those
  go to docs/decisions/lightweight-decisions.md via decisions.py. Also use when
  revising, updating, or re-pricing an already-recorded decision: judge whether it
  now warrants an ADR and promote it if so, rather than editing it in place. Also
  auto-fires at session end. Do not use for updating specs or code comments. For a
  NEW load-bearing decision, one with rejected alternatives, or any the user wants
  written up as an ADR, use `/jig:adr-workflow`; an already-recorded entry that
  outgrew this home is promoted from here.
user-invocable: true

> Spec 002 (memory layer) is fully closed — all four slices DONE: 002-01 > (explicit-sync), 002-02 (lookup-pattern), 002-03 (auto-detect-hooks), > 002-04 (reconciliation-integration). 002-04's reconciliation integration > is now the Memory-sync gate in the spec-workflow reconciliation checklist.

What this skill does

Persists session-derived context to the memory layer via a deterministic helper. Claude makes the *what / where* decisions; `memory.py` does the file I/O, idempotency, and self-healing of missing memory structure.

When to invoke

• User says "remember this", "save this for later", "add this to the glossary",

"note this down", or similar (→ persist flow below).

• User explicitly invokes `/jig:memory-sync`.
• An unknown capitalized reference appears in the conversation (→ lookup-pattern flow below).
• Session-end consolidation (after slice 002-03 auto-trigger ships).
• **The session settled a non-spec shipped decision** — a UI string, visual/CSS

choice, translation correction, or scoped brand/icon call made *outside* a spec slice (→ lightweight-decision flow below). This is the forcing function for out-of-spec work, which has no reconciliation phase to catch it.

Lookup-pattern flow

When you see a capitalized reference, acronym, or project-specific term you don't recognize, follow this flow **before asking the user**:

seen unknown reference X
  ↓
python3 memory.py lookup "X" .
  ↓ exit 0 → use the printed definition; do not ask
  ↓ exit 2 → ask the user once: "I don't recognize X — what is it?"
  ↓ user answers
  ↓
python3 memory.py add-term "X" "<definition>" .   (or promote if high-frequency)
  ↓ next time X appears, lookup hits

Concretely, the commands are:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/memory-sync/memory.py" lookup "<term>" "<target>"
# exit 0 = hit (definition + source on stdout)
# exit 2 = miss (proceed to ask the user)

The lookup is case-insensitive and checks hot cache first, then glossary. Hot cache hits win when a term exists in both (the user has explicitly elevated it).

**Do not ask twice.** Once a term is persisted (via `add-term` or `promote`), future lookups in the same or later sessions resolve without re-asking. If the user says "I told you this already," check whether you forgot to persist last time, then persist now.

How to use

1. **Identify candidate items** from the recent session:

• **New domain terms** — anything the user defined or that needed explaining.
• **Learnings** — failed approaches, dead ends, "we tried X" gotchas.
• **Parked ideas** — things mentioned but not yet decided on.
• **Frequently-referenced terms** — anything used ≥3 times this session.
• **Non-spec shipped decisions** (spec 083) — UI strings, visual/CSS choices,

translation corrections, scoped brand/icon calls settled *outside* a spec slice. **Conditional, to avoid noise:** only surface this when the session actually touched such product/UI/out-of-spec work — skip it entirely for pure backend/refactor/spec sessions.

• **Load-bearing decision escape hatch** (spec 083-06 / ADR-0031) — the

enumerated surface list above is **not** a closed gate. This session-end prompt is the **only** judgment owner for *out-of-spec* load-bearing decisions (which have no reconciliation phase), so also surface — regardless of which surface was touched — any decision the canonical ADR trigger covers. Canonical wording — single-sourced from ADR-0031, drift-tested verbatim across all four surfaces: A load-bearing design choice with rejected alternatives — one a future agent would need to know about to avoid undoing it — warrants an ADR even when it changes no module boundary or public contract. 2. **Decide per item** which file it belongs in:

• Niche/domain term → glossary
• Failed approach / gotcha → learnings
• Unresolved/unfinished thought → inbox
• High-frequency term → hot cache (in CLAUDE.md)
• Non-spec shipped decision → `docs/decisions/lightweight-decisions.md`

3. **Invoke `memory.py` once per item** with the right command. **Always quote the term/definition/body arguments** — terms may contain spaces, definitions often contain punctuation:

   python3 "${CLAUDE_PLUGIN_ROOT}/skills/memory-sync/memory.py" add-term "<name>" "<definition>" "<target>"
   python3 "${CLAUDE_PLUGIN_ROOT}/skills/memory-sync/memory.py" add-learning "<title>" --body "<text>" "<target>"
   python3 "${CLAUDE_PLUGIN_ROOT}/skills/memory-sync/memory.py" add-inbox "<text>" "<target>"
   python3 "${CLAUDE_PLUGIN_ROOT}/skills/memory-sync/memory.py" add-refinement-todo "<raw-markdown-chunk>" "<target>"
   python3 "${CLAUDE_PLUGIN_ROOT}/skills/memory-sync/memory.py" promote "<term>" "<definition>" "<target>"

`add-refinement-todo` appends raw text (caller composes the markdown chunk — H