ums

name	ums
description	Update memories and skills.
user-invocable	true
allowed-tools	["Bash","Read","Edit","Write"]

UMS — Update Memories and Skills

Actively review recent session context and update all relevant memory files and skill definitions to capture what was learned. Unlike record-learnings (which records individual facts in place as they arise), UMS is a reflective checkpoint: survey what accumulated, categorize it, and persist it all in one committed pass.

When this fires

• As soon as a learning worth saving shows up — a corrected mistake, a new preference, a tool quirk, a workflow gap. This is the primary trigger: run UMS right then, interleaved with the main work, instead of batching learnings for a wrap-up step at the end. Don't wait for the task to finish or for /clear to accumulate a backlog — and don't gate it on approval or on a PR merging: capture the learning the moment it appears, even while the PR that taught it is still open and unreviewed. A user correction is a mandatory immediate trigger. Persist the lesson before resuming the main task; never wait for the user to invoke UMS or remind you a second time.
• When you read a review of your work, receive critical feedback on it, or a questioned claim turns out to be wrong. The trigger is the scrutiny, not Address, not a clean verdict, and not a first-person admission. "Are you sure about that?" is the questioning case: check the claim, and if it was wrong, run UMS --- answering with the corrected fact is not the pass. Questioning alone does not owe a pass when the claim holds. See run-ums-proactively.
• When a PR reaches a clean review verdict -- the checkpoint the ardi loop exits on, and the backstop if the user-correction trigger or the scrutiny trigger above was skipped. Run the pass there rather than at the merge: the merge is human-gated and may land long after this session ends, while the verdict is the moment the review lifecycle has finished teaching.
• Even when a new request arrives at that same moment -- the mechanism that actually skips the user-correction trigger, the scrutiny trigger, and the clean-verdict checkpoint. A merge or clean verdict is when you report back, so it is also when the next instruction lands, and that instruction reads as the live task while the owed pass quietly evaporates: never refused, never deferred out loud, just never performed. A new request does not cancel a checkpoint. Run the pass first (it is short), or say in the same reply that it is owed and when it will run. Deferring out loud is fine; dropping it silently is the failure. Watch for it too when a skill ends in a UMS step (post-merge, ardi, wrap-up): reporting that skill complete asserts its final step ran, so confirm the pass happened rather than only the steps before it.
• User says "ums", "update memories and skills", "record what we learned"
• At the start of /clear — a backstop, not the primary trigger: catch anything accumulated since the last proactive pass before context is lost
• After a workflow reveals a gap (e.g., a skill was followed but missed a step, or a preference wasn't encoded)
• When the user says "did you update memories?" (the answer should be "let me do that now")
• While paused waiting on a subagent or a long-running background process to complete. That idle stretch is exactly when there's time to survey what's accumulated so far and persist it, rather than only running UMS at a hard stop. Don't let a real wait sit fully idle when a useful pass is available to run alongside it.

Procedure

1. Scan recent context. Review the conversation for:

   • Mistakes made and corrected (skill gaps)
   • New preferences expressed by the user
   • Tool quirks discovered
   • Workflow steps that were missing or unclear in existing skills
   • Debugging insights
   • Codebase conventions discovered

2. Categorize each learning. For each item, decide:

   • Is it a skill update? (workflow step missing, procedure unclear)
   • Is it a memory note? (tool quirk, preference, debugging insight)
   • Is it both? (general guidance → update skill AND preferences)
   • Is it already recorded? (grep before writing -- avoid duplicates)
   • Is it cross-project or project-specific? (memories/preferences.md's "Memory and skill storage" rule: cross-project lessons commit to Morrison-Lab/ai-config; a convention/gotcha tied to one repo we own commits to that repo's own agent docs instead — see the checklist item below for where. This changes step 4's target, not just the content.)

3. Apply updates. For each item:

   • Read the target file first (skill or memory) to understand current state

   • Grep that file for the item's specific subject -- the tool name, the API call, the error string -- before appending anything. Reading the region you're editing is not enough: a topical memory file runs to hundreds or a thousand-plus lines, so an existing entry on the same subject can sit far away in an unrelated cluster and never enter your view. Grep the whole memories/ directory rather than one file -- a fact can plausibly sit in either of two adjacent topical files. When one exists, extend it in place; don't add a second bullet. (ai-config#689: a list_workflow_runs cost bullet went in next to the related get_check_runs guidance while an entry on the same tool already sat ~2000 lines below in the write-access cluster -- caught by the review bot, not by the author.)

   • When the target memory file is already at the 1200-line cap, recover lines (re-wrap or drop) or split the file. A fold has two shapes and neither escapes every gate: a new source line trips scripts/test_check_memory_file_size.py, while folding the sentence into an existing line leaves the count flat but makes that line a changed line the new-line-breaks gate can flag. A net-positive append fails even when every new sentence is a real lesson (3rd occurrence, 2026-08-25 on in ai-config#2262: was exactly 1200 lines, and a +5-line append reddened . Prior: ai-config#1291; ai-config#811).

What to look for (checklist)

• Did I follow a skill but miss a step? → Update the skill

• Did the user correct my behavior? → Encode as preference + skill update

• Did I discover a tool quirk? → the matching topical file under /memories/ (memories/MEMORY.md lists the current set; tools.md when it fits none of them)

• Did I learn a debugging pattern? → /memories/debugging.md

• Did I create a new file under /memories/? → register it in memories/MEMORY.md as an index entry

• Did I discover a repo convention for a repo we own that has checked-in agent docs? → put it IN that repo (its CLAUDE.md, .github/agents/*.md, .github/instructions/*.md, .github/copilot-instructions.md, or checked-in .claude/memories/), via a PR, so the whole team and every @claude session there sees it. Do NOT keep repo-specific notes in ai-config (memories/repo/ is retired). For a repo without agent-doc infrastructure yet, write to this session's own local project-memory mechanism (Claude Code: ~/.claude/projects/<project-path>/memory/ — a non-Claude session should use whatever the equivalent local staging location is for its own agent) as short-lived staging only — hand off that a PR adding agent docs to that repo is still required.

• Did the user express a new preference? → /memories/preferences.md

• Did a workflow emerge that could be a new skill? → run spot-skill-opportunities to judge whether it's genuinely recurring, then skill-builder to create it

• Did a heavy skill's fan-out step need a dedicated read-only worker persona (like dependency-auditor / hallucination-detector / community-demand-scout), rather than just a new skill? → run to scaffold

Relationship to record-learnings and staged capture

• record-learnings = records individual facts in place, in the moment they arise
• ums = a reflective, full-context sweep — survey what accumulated, categorize it, and persist it all in one committed pass

Both write to the same destinations. ums fires proactively, as soon as a learning worth saving shows up, rather than waiting to catch up later; the /clear trigger is only a backstop for anything that slipped through.

spot-skill-opportunities is the standing, continuous version of this skill's "did a workflow emerge that could be a new skill?" checklist item — it runs the recognition judgment call live, in the moment, instead of only at this checkpoint. agent-builder is the sibling construction step for the other checklist item above — a recurring fan-out worker persona rather than a new user-invocable skill.

learn/promote-memory are a staged alternative for the uncertain case: record-learnings and this skill both write directly to committed memory the moment something looks worth remembering, which is right when you're confident. When you're not — a candidate whose generality or evidence isn't solid yet — learn stages it instead, and a promote-memory pass (which a ums run can fold in, or run standalone) reviews staged candidates before they land in committed memory. Neither replaces the direct-write path; they add a review gate for the cases that need one.

Anti-patterns

• ❌ Saying "I'll remember that" without actually writing it down
• ❌ Updating memories but not pushing skill changes to origin
• ❌ Recording vague lessons ("be more careful") instead of specific ones ("always poll for new review after pushing — check commit SHA matches")
• ❌ Skipping the "check existing notes" step and creating duplicates -- specifically, reading only the region you're appending to instead of grepping the whole target file for the subject (step 3)
• ❌ Updating only preferences when a skill also needs the fix
• ❌ git add -A — it sweeps unrelated in-flight edits (the user's work, other draft skills) into your commit/PR. Stage the specific files you touched.
• ❌ Creating memories/repo/<repo>.md for any repo — this pattern is retired. Put repo-specific lore in the repo's own agent docs (.github/agents/, CLAUDE.md, .github/instructions/, .github/copilot-instructions.md, or checked-in .claude/memories/) via a PR; if the repo has no agent-doc infrastructure yet, this session's own local project-memory mechanism (Claude Code: ~/.claude/projects/<project-path>/memory/ — substitute the equivalent for a non-Claude agent) is short-lived staging only — hand off that a PR adding those agent docs is still required. See the checklist item above and memories/preferences.md for the full rule.
• ❌ Naming a tool, flag, or API identifier that appears nowhere else in the corpus without anchoring it somewhere checkable. A lone mention reads identically whether it is correct or hallucinated, so a later session has nothing to verify it against --- and the guidance is only actionable if the name is right. When the identifier is a cross-model tool, add it to tool-mappings.yml (then regenerate) rather than leaving the memory bullet as its only home; otherwise cite where you confirmed it. Having used it successfully in the session you're writing up is good evidence, but that evidence dies with the session. (ai-config#727: mcp__github__list_commits was flagged in review as unanchored; it was genuinely verified by use, and the fix was registering it as the LIST_COMMITS operation.)
• ❌ Inserting a new bullet into any memory file with nested lists (including github-actions.md, preferences.md) without checking the surrounding indentation first. These files mix 0-indent top-level bullets with 2-/4-indent sub-bullets and multi-paragraph continuations; a new top-level bullet dropped in the middle of an existing parent's sub-list re-parents whatever follows it in Markdown (a sibling sub-bullet silently becomes this new bullet's child). Before committing an insertion, re-read the few lines immediately above and below the insertion point and confirm the indentation still matches what it did before — or place the new bullet after the complete enclosing list instead of inside it. (Caught by review on ai-config#335: a new 0-indent bullet landed between two sibling sub-bullets of an existing parent, breaking the nesting.)