[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M735B9TXHD2RVQFPAJM893XR":3,"skill-same:01M735B9TXHD2RVQFPAJM893XR":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":33,"repositoryHtmlUrl":34,"repositoryHomepageUrl":35,"ownerHtmlUrl":36,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":37,"install":38,"resources":50},"01M735B9TXHD2RVQFPAJM893XR","ums",null,"Update memories and skills.","Morrison-Lab\u002Fai-config","Morrison-Lab","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F104235520?v=4","01M734G0451S2G35MN4HFQK7XP","Morrison Lab","01M734G059BYFDFQA8YTPDGPMH",4,"MIT","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fums\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: ums\ndescription: \"Update memories and skills.\"\nuser-invocable: true\nallowed-tools:\n  - Bash\n  - Read\n  - Edit\n  - Write\n---\n\n# UMS — Update Memories and Skills\n\nActively review recent session context and update all relevant memory files\nand skill definitions to capture what was learned. Unlike `record-learnings`\n(which records individual facts in place as they arise), UMS is a reflective\ncheckpoint: survey what accumulated, categorize it, and persist it all in one\ncommitted pass.\n\n## When this fires\n\n- **As soon as a learning worth saving shows up** — a corrected mistake, a\n  new preference, a tool quirk, a workflow gap. This is the primary trigger:\n  run UMS right then, interleaved with the main work, instead of batching\n  learnings for a wrap-up step at the end. Don't wait for the task to finish\n  or for `\u002Fclear` to accumulate a backlog — and don't gate it on approval or\n  on a PR merging: capture the learning the moment it appears, even while the\n  PR that taught it is still open and unreviewed.\n  **A user correction is a mandatory immediate trigger.** Persist the lesson\n  before resuming the main task; never wait for the user to invoke UMS or\n  remind you a second time.\n  **User profanity or frustration is an urgent trigger.**\n  It signals a severe mistake, broken assumption, or dropped preference\n  requiring immediate diagnosis, repair, and learning\n  (see [`user-profanity-signal`](..\u002F..\u002Fshared\u002Fworkflow\u002Fuser-profanity-signal.md)).\n- **When you read a review of your work, receive critical feedback on it,\n  or a questioned claim turns out to be wrong.**\n  The trigger is the scrutiny, not Address, not a clean verdict, and not\n  a first-person admission.\n  \"Are you sure about that?\" is the questioning case: check the claim, and\n  if it was wrong, run UMS --- answering with the corrected fact is not\n  the pass.\n  Questioning alone does not owe a pass when the claim holds.\n  See\n  [`run-ums-proactively`](..\u002F..\u002Fshared\u002Fworkflow\u002Frun-ums-proactively.md).\n- **When a PR reaches a clean review verdict** -- the checkpoint the\n  `ardi` loop exits on, and the backstop if the user-correction trigger\n  or the scrutiny trigger above was skipped.\n  Run the pass there rather than at the merge: the merge is human-gated and\n  may land long after this session ends, while the verdict is the moment the\n  review lifecycle has finished teaching.\n- **Even when a new request arrives at that same moment** -- the mechanism\n  that actually skips the user-correction trigger, the scrutiny trigger,\n  and the clean-verdict checkpoint.\n  A merge or clean verdict is when you report back, so it is also when the\n  next instruction lands, and that instruction reads as the live task while\n  the owed pass quietly evaporates: never refused, never deferred out loud,\n  just never performed.\n  A new request does not cancel a checkpoint.\n  Run the pass first (it is short), or say in the same reply that it is owed\n  and when it will run.\n  Deferring out loud is fine; dropping it silently is the failure.\n  Watch for it too when a skill *ends* in a UMS step (`post-merge`, `ardi`,\n  `wrap-up`): reporting that skill complete asserts its final step ran, so\n  confirm the pass happened rather than only the steps before it.\n  Loading the skill is not confirmation.\n  A valid no-change pass must still complete the context scan and, for every candidate, categorize it and grep the destination's full `memories\u002F` directory plus the relevant skill and shared-workflow files;\n  report the candidates and searches instead of merely asserting that no update was needed. (Recurrence, 2026-09-14: after a merge, the skill was loaded and one narrow grep was run, but the merge was reported wrapped up with \"UMS review found no additional durable memory update needed\";\n  the user's \"what about ums?\" exposed that the actual pass had never run.)\n- User says \"ums\", \"update memories and skills\", \"record what we learned\"\n- **At the start of `\u002Fclear`** — a backstop, not the primary trigger: catch\n  anything accumulated since the last proactive pass before context is lost\n- After a workflow reveals a gap (e.g., a skill was followed but missed a\n  step, or a preference wasn't encoded)\n- When the user says \"did you update memories?\" (the answer should be \"let\n  me do that now\")\n- **Before ending a turn to wait on anything** --- a subagent,\n  a long-running background process, CI, a review round,\n  or an answer from the user.\n  Run the pass before the turn ends,\n  not once the wait turns out to be long:\n  a wait's length is not knowable when it begins,\n  and the learnings sit in conversation state until it ends.\n  A dispatched subagent or background job is the case\n  where the pass runs alongside the wait rather than delaying it,\n  so don't let a real wait sit fully idle.\n  The pass is owed at the first pause\n  and again only once new learnings accumulate,\n  rather than once per wait or once per re-arm of a timer.\n  See\n  [`run-ums-proactively`](..\u002F..\u002Fshared\u002Fworkflow\u002Frun-ums-proactively.md).\n\n## Procedure\n\n1. **Scan recent context.** Review the conversation for:\n   - Mistakes made and corrected (skill gaps)\n   - New preferences expressed by the user\n   - Tool quirks discovered\n   - Workflow steps that were missing or unclear in existing skills\n   - Debugging insights\n   - Codebase conventions discovered\n\n   *(When delegating UMS to a subagent, prefer **conversation-inheriting dispatch**\n   (Agent `subagent_type: \"fork\"` or `\u002Fsubtask` in Claude Code, or providing the transcript log path in clean-slate harnesses)\n   so the subagent surveys conversation history directly without manual serialization;\n   see [`use-subagents`](..\u002F..\u002Fshared\u002Fworkflow\u002Fuse-subagents.md).)*\n\n2. **Categorize each learning.** For each item, decide:\n   - Is it a **skill update**? (workflow step missing, procedure unclear)\n   - Is it a **memory note**? (tool quirk, preference, debugging insight)\n   - Is it **both**? (general guidance → update skill AND preferences)\n   - Is it already recorded? (grep before writing -- avoid duplicates)\n   - Is it **cross-project or project-specific**? (`memories\u002Fpreferences.md`'s\n     \"Memory and skill storage\" rule: cross-project lessons commit to\n     `Morrison-Lab\u002Fai-config`; a convention\u002Fgotcha tied to one repo we own\n     commits to *that* repo's own agent docs instead --- see the checklist\n     item below for where. This changes step 4's target, not just the\n     content.)\n\n3. **Apply updates.** For each item:\n   - Read the target file first (skill or memory) to understand current state\n   - **Grep the corpus for the item's specific subject** -- the tool name, the\n     API call, the error string -- before appending anything.\n     Reading the region you're editing is not enough: a topical memory file\n     runs to hundreds or a thousand-plus lines, so an existing entry on the\n     same subject can sit far away in an unrelated cluster and never enter\n     your view.\n     Grep [`skill-builder`](..\u002Fskill-builder\u002FSKILL.md) step 0's path list\n     rather than one file, and rather than only `memories\u002F`:\n     ```bash\n     (\n       repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || git rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n       test -f \"$repo\u002FCLAUDE.md\" && test -d \"$repo\u002Fshared\" || { echo \"not an ai-config checkout: $repo\" >&2; exit 1; }\n       cd \"$repo\" && grep -rilIF -- \"\u003Csubject>\" skills\u002F scripts\u002F hooks\u002F shared\u002F memories\u002F CLAUDE.md\n     )\n     ```\n     The query runs over the files on disk,\n     so an entry that exists only on a branch not checked out there is out of reach\n     (see the unmerged-PR section of [`grep-is-not-coverage`](..\u002F..\u002Fshared\u002Fworkflow\u002Fgrep-is-not-coverage.md)).\n     `-F` matches the subject as a fixed string,\n     so an error string carrying `[`, `.`, or `*` is searched for as written;\n     `-I` skips binary files, bytecode caches included,\n     which a plain `grep -r` would otherwise report as hits.\n     A rule can be owned by a `shared\u002F` fragment or a skill as easily as by a memory,\n     and a `memories\u002F`-only grep stays outside those paths.\n     When the grep finds an existing entry on the subject, extend that entry in place;\n     don't add a second bullet.\n     (ai-config#689: a `list_workflow_runs` cost bullet went in next to the\n     related `get_check_runs` guidance while an entry on the same tool already\n     sat ~2000 lines below in the write-access cluster -- caught by the review\n     bot, not by the author.)\n   - **Run `python3 scripts\u002Fcheck-memory-file-size.py` before writing the\n     append, and read its warning band, not only its pass\u002Ffail line.**\n     The band names every memory file near the cap and how many lines each\n     has left (ai-config#3102), so a file with almost no\n     headroom is knowable here, while the entry can still be re-wrapped or the\n     file split, rather than by tripping the gate in step 4 once the append is\n     written.\n     Read each listed file's headroom, not its membership: the band opens 100\n     lines below the cap at the shipped default, so most of it is room rather\n     than a warning.\n     - **Do:** read the reported headroom of the file the entry topically\n       belongs in, and recover lines or split that file when its headroom does\n       not comfortably cover the entry.\n     - **Don't:** pick the destination by headroom rather than by subject,\n       or redirect or split on band membership alone --- a file with most of\n       the band still ahead of it can take this entry.\n   - **When the target memory file is already at the cap\n     `scripts\u002Fcheck-memory-file-size.py` reports**,\n     recover lines (re-wrap or drop) or split the file.\n     A fold has two shapes and neither escapes every gate: a new source\n     line trips `scripts\u002Ftest_check_memory_file_size.py`, while folding\n     the sentence into an existing line leaves the count flat but makes\n     that line a changed line the new-line-breaks gate can flag.\n     A net-positive append fails\n     `scripts\u002Ftest_check_memory_file_size.py`\n     even when every new sentence is a real lesson\n     (5th occurrence, 2026-10-07 on `memories\u002Fmistake-patterns.md`, PR #4348:\n     `main` sat at 1244 lines with 6 lines of headroom,\n     and appending Pattern 62 pushed the file to 1261 lines,\n     breaching `scripts\u002Fcheck-memory-file-size.py --strict` in CI `validate.yml`;\n     files within 10 lines of the 1250-line limit must be split or condensed,\n     not appended past the cap;\n     4th occurrence, 2026-09-09 on `memories\u002Fmistake-patterns.md`,\n     found by a scheduled PR-sweep session rather than by a push: `main` sat\n     exactly at the cap, 1250 lines \u002F 61 `## Pattern` headings, at the exact\n     value `--max-lines` defaults to, with zero headroom -- confirmed via\n     `python3 scripts\u002Fcheck-memory-file-size.py --strict` (exit 0, \"0 lines\n     of headroom\") and independently via PR #3386's head (`3f58d9b6`, 1275\n     lines \u002F 62 headings) failing `validate`'s size check.\n     The consequence is not scoped to whichever PR crosses the line: with the\n     file already full, every other open PR that appends a pattern --\n     unrelated in content, no larger than any prior append -- fails the same\n     check the moment it is pushed, which is easy to misread as a defect in\n     that PR rather than as pre-existing headroom exhaustion.\n     The split is tracked in ai-config#3340, filed 2026-09-07 and still open;\n     check it before re-filing.\n     Prior: `memories\u002Fpreferences.md` ai-config#2262 (3rd, 2026-08-25:\n     `origin\u002Fmain` sat exactly at the cap, 1200 lines as that cap then stood,\n     and a +5-line append reddened `validate`);\n     `shared\u002Fwriting\u002Fsemantic-line-breaks.md` ai-config#1291;\n     `shared\u002Fworkflow\u002Freview-verdict-pitfalls.md` ai-config#811).\n   - **When the file to split enforces its own numbering invariant,\n     \"move whole sections\" is not automatic.**\n     `memories\u002Fmistake-patterns.md`'s `## Pattern N:` headings are checked\n     by `scripts\u002Fcheck-mistake-patterns.py`,\n     which requires the integers to run `1..K` in file order with no gap\n     (a lettered sub-pattern like `5c` follows its base entry\n     and advances by letter).\n     Lifting a non-contiguous subset out ---\n     exactly what ai-config#3340 proposes\n     (Patterns 21, 43, 50, 51, 52, 55) ---\n     opens a gap the checker rejects\n     unless every later heading is renumbered,\n     or the lifted headings are kept as stub pointers in place.\n     Every citation by number then needs the same repoint:\n     at least 27 files outside `memories\u002Fmistake-patterns.md` itself\n     cite a pattern by number\n     (`grep -rlE 'Pattern [0-9]+[a-z]?\\b' --include='*.md' --include='*.py' .`,\n     filtered for two unrelated numbered-list false positives ---\n     `skills\u002Fcli\u002Freferences\u002Fconditions.md`'s own \"Pattern 1\u002F2\u002F3\u002F4\"\n     and `skills\u002Fdetect-informal-definitions\u002FSKILL.md`'s\n     \"Pattern 1\"\u002F\"Pattern 2\"\u002F\"Pattern 3\" ---\n     and one synthetic test fixture,\n     `scripts\u002Ftest_check_mistake_patterns.py`,\n     which types pattern numbers that never existed to exercise the regex).\n     The file also carries its own in-file directional cross-references\n     (\"Pattern 25 above\" at line 544, \"Pattern 20 below\" at line 451,\n     seven total)\n     that a move falsifies without breaking any link a grep would catch.\n     - **Do:** before moving any `## Pattern N:` section out of\n       `mistake-patterns.md`,\n       grep the whole repo for `Pattern N`\n       and repoint every genuine hit, including in-file \"above\"\u002F\"below\" wording,\n       after excluding unrelated numbered-list prose\n       by reading each match rather than trusting the grep's raw file count.\n     - **Do:** either renumber every heading after a lifted gap\n       so `check-mistake-patterns.py` still reads `1..K` with no gap,\n       or leave a stub `## Pattern N:` heading pointing at the new file,\n       rather than deleting the number outright.\n     - **Don't:** move a non-contiguous subset of patterns to a satellite file\n       on the strength of `check-memory-file-size.py`'s own generic\n       \"move whole sections, repoint inbound references\" advice ---\n       that advice is about the size gate alone\n       and says nothing about the separate contiguity gate\n       `check-mistake-patterns.py` enforces.\n     - **Don't:** treat a raw `grep -rl` file count as the citation count to repoint ---\n       a numbered-heading pattern like `Pattern N` recurs in unrelated prose\n       elsewhere in the repo,\n       and counting those inflates the sweep without finding anything to fix.\n   - **When step 2 routed the item to a repo other than ai-config, grep both\n     corpora.**\n     The query above searches an ai-config checkout,\n     so run a second pass in the destination repo, over that repo's own doc paths ---\n     a repo-local entry can otherwise duplicate or contradict a fragment\n     nobody thought to search from that repo.\n     See\n     [`grep-is-not-coverage`](..\u002F..\u002Fshared\u002Fworkflow\u002Fgrep-is-not-coverage.md)'s\n     \"Searching the wrong corpus is the same error with no grep in it\".\n   - **When the subject grep finds an existing entry covering this class, record the\n     recurrence on the existing entry, not just the new fact.**\n     The **Grep the corpus** bullet above already says to extend in place\n     rather than add a sibling;\n     what is missing is the count.\n     Write it on the entry -- \"3rd occurrence, 2026-08-16\", with a pointer to\n     each prior record -- so the entry carries evidence about whether the\n     written rule is actually holding.\n\n     The count has a consumer that already exists and currently has nothing to\n     read.\n     [`deterministic-tools`](..\u002F..\u002Fshared\u002Fprinciples\u002Fdeterministic-tools.md)\n     names the third occurrence as the moment a recurring judgment task becomes\n     a tool, and\n     [`learn-from-review-findings`](..\u002F..\u002Fshared\u002Fworkflow\u002Flearn-from-review-findings.md)\n     asks of every accepted finding whether it is algorithmatizable -- but\n     nothing in the corpus counts, so that trigger fires on recollection or not\n     at all.\n     A rule on its third recurrence is a rule demonstrably not holding, which\n     is the argument for a hook or a check rather than for a sharper sentence.\n\n     A recurrence note is also a duplication signal for\n     [`find-overlap`](..\u002Ffind-overlap\u002FSKILL.md) and\n     [`consolidate-memory`](..\u002Fconsolidate-memory\u002FSKILL.md), since one class\n     recorded twice under different wording is exactly the near-duplicate a\n     phrase-similarity pass under-detects.\n     The reverse reading -- an entry that has never recurred and is never cited\n     is a retirement candidate -- has **no** consumer today, so treat it as a\n     property the count makes available rather than as a step anything runs.\n   - Make the edit --- concise bullet points, not prose\n   - If updating a skill: the change should be specific enough that following\n     the skill next time would avoid the mistake\n\n4. **Commit and push --- via a branch + PR, not direct to `main`, in whichever\n   repo step 2 routed the item to.**\n\n   If the work will dispatch an expensive external action from a pinned commit\n   (such as a release, deployment, or batch computation), create, push, and\n   open the PR **before** dispatching it. The PR is the reviewable record of the\n   exact SHA that performed the action; opening it afterward is too late.\n\n   **Do this in an isolated `git worktree`, not the shared ai-config checkout\n   directly** -- `memories\u002Fpreferences.md`'s \"Run a local session in an\n   isolated git worktree by DEFAULT\" rule applies here too.\n   The shared checkout is routinely in concurrent use by other sessions also\n   running UMS; a `git checkout \u003Cbranch>` from another session mid-command\n   can silently redirect *your* `git commit`\u002F`git push` onto *their* branch\n   (and vice versa), and a local `git status`\u002F`git log` read moments later\n   can already reflect a third session's activity, not your own.\n   Every code block below creates (or reuses) a worktree first, then runs\n   every `git add`\u002F`commit`\u002F`push` from inside it -- never `cd` straight\n   into the shared checkout itself to make a change.\n\n   **Run the repo's own gates on the files you touched before the commit**,\n   since a UMS PR fails CI on the same checks as any other:\n   `python3 scripts\u002Fcheck-memory-file-size.py --strict` (a memory file over\n   1250 lines fails; split it, as `memories\u002Fmarkdownlint.md` was split from\n   `tools.md` on 2026-09-01 when a UMS append crossed the budget),\n   `NLB_BASE_REF=origin\u002Fmain python3 scripts\u002Fvendor\u002Fgha-check-new-line-breaks.py`,\n   `python3 scripts\u002Fcheck-links.py`, and `markdownlint` on the changed files.\n\n   `check-memory-file-size.py` prints its warning band here too, but this run\n   is the pass\u002Ffail one: the band is actionable in step 3, before the append is\n   written, and by now the append already exists.\n\n   **If a push is rejected non-fast-forward:** fetch first and diff before\n   assuming a real conflict -- the branch may have picked up another\n   session's commit that needs separating out (`git revert \u003Ctheir-commit>`)\n   rather than force-pushing over it.\n   Verify the PR's real, current content via `gh api\n   repos\u002F\u003Cowner>\u002F\u003Crepo>\u002Fpulls\u002F\u003CN>\u002Ffiles` or `git ls-remote`\u002F`git show\n   origin\u002F\u003Cbranch>:\u003Cpath>` (the GitHub-side truth), not the local checkout,\n   which may have already moved again.\n   (ai-config#748: a UMS commit collided with another concurrent session's\n   UMS commit on a shared branch name this way -- both sessions' content\n   ended up interleaved on one branch before separating back out, resolved\n   without data loss only because both sides fetched-before-pushing and\n   diffed before force-acting.)\n\n   **Cross-project items** (skills, cross-project memory notes): both live in\n   the ai-config repo. Discover its path with\n   `${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}` — point\n   `-C` at a **skill subdir** (any one), not the `~\u002F.claude\u002Fskills` parent.\n   `bootstrap.sh` may symlink skills *per-child* into a real `~\u002F.claude\u002Fskills`\n   directory (cloud\u002Fweb sessions pre-populate it), so the parent itself isn't a\n   symlink into the repo and `git -C` there fails with \"not a git repository\";\n   a child like `…\u002Fskills\u002Fums` follows the symlink into the repo. (Both beat the\n   older `dirname \"$(readlink …)\"`, which resolves only one symlink hop.) Never\n   leave ANY changes (skills, memories, etc.) as local-only uncommitted edits.\n   Run **one** of the two paths below — not both:\n\n   **Stage only the files you actually edited — NEVER `git add -A`.** The\n   working tree often holds unrelated in-flight edits (the user's own UMS\n   commits, another skill being drafted); `git add -A` sweeps those into your\n   commit and onto your PR, where they bloat the review and extend the cycle.\n   List the specific paths instead. Then **`git status` to confirm only your\n   intended files are staged** — if something unexpected is there, the working\n   tree had in-flight work; unstage it rather than bundling it. (Avoid\n   `git add -p` here: it needs a terminal and hangs in non-interactive sessions.)\n\n   Every path below starts by resolving `$repo`, the shared checkout's path\n   (read-only -- discovering the path doesn't touch the shared working\n   directory), then creates or reuses a **worktree** off it and does every\n   write from inside that worktree instead.\n\n   *Already on the open PR's branch* (e.g. mid-ARDI): reuse a worktree for\n   it, creating one if this is the first push in the worktree-ified flow.\n   ```bash\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   wt=\"..\u002Fai-config-worktrees\u002F\u003Cbranch>\"\n   git -C \"$repo\" worktree add \"$wt\" \"\u003Cbranch>\" 2>\u002Fdev\u002Fnull || true   # no-op if it already exists\n   cd \"$wt\"\n   git add \"skills\u002F\u003Cname>\u002FSKILL.md\" \"memories\u002F\u003Cfile>.md\"   # the files you touched\n   git commit -m \"ums: \u003Cbrief summary>\"   # COMMIT\n   ```\n\n   Push as a separate Bash call, per [`check-before-pushing`](..\u002F..\u002Fshared\u002Fworkflow\u002Fcheck-before-pushing.md)'s \"Keep the commit in its own Bash call\":\n\n   ```bash\n   # `git -C`, not `cd`: whether a separate Bash call keeps the\n   # previous one's directory is unsettled between sessions, so a\n   # relative `cd` breaks in whichever half it did not assume.\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\u002F..\u002Fai-config-worktrees\u002F\u003Cbranch>\" push origin HEAD   # PUSH\n   ```\n\n   *No PR yet:* branch off main first — a direct-to-main push is denied by\n   auto-mode and bypasses review.\n\n   *Same-repo case* (this checkout's `origin` IS the repo you're targeting):\n   ```bash\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\" fetch origin main   # FETCH\n   git -C \"$repo\" worktree add -b \"ums-\u003Ctopic>\" \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" origin\u002Fmain   # CREATE_BRANCH\n   cd \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\"\n   git add \"skills\u002F\u003Cname>\u002FSKILL.md\" \"memories\u002F\u003Cfile>.md\"   # the files you touched\n   git commit -m \"ums: \u003Cbrief summary>\"   # COMMIT\n   ```\n\n   Push as a separate Bash call, per [`check-before-pushing`](..\u002F..\u002Fshared\u002Fworkflow\u002Fcheck-before-pushing.md)'s \"Keep the commit in its own Bash call\":\n\n   ```bash\n   # `git -C`, not `cd`: whether a separate Bash call keeps the\n   # previous one's directory is unsettled between sessions, so a\n   # relative `cd` breaks in whichever half it did not assume.\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\u002F..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" push -u origin HEAD   # PUSH -- PR creation is handled by the post-push verification step below\n   ```\n\n   *Cross-fork case* (this checkout's `origin` is your own fork, not the\n   upstream repo you're targeting): don't branch from a bare `origin\u002Fmain`\n   here -- the fork's `main` can be stale relative to upstream's default\n   branch. Fetch the intended **upstream** repo explicitly (not just look up\n   its default-branch name) and branch the worktree from that fetched ref:\n   ```bash\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   base=\"$(gh repo view \"\u003Cupstream-owner>\u002F\u003Crepo>\" --json defaultBranchRef -q .defaultBranchRef.name)\" \\\n     && git -C \"$repo\" fetch \"https:\u002F\u002Fgithub.com\u002F\u003Cupstream-owner>\u002F\u003Crepo>.git\" \"$base\" \\\n     && git -C \"$repo\" worktree add -b \"ums-\u003Ctopic>\" \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" FETCH_HEAD\n   # chained with && on purpose -- a failed lookup or fetch must stop the\n   # worktree creation, or it silently reuses an older FETCH_HEAD from a\n   # prior fetch, recreating the stale-base problem this block exists to prevent\n   cd \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\"\n   git add \"skills\u002F\u003Cname>\u002FSKILL.md\" \"memories\u002F\u003Cfile>.md\"   # the files you touched\n   git commit -m \"ums: \u003Cbrief summary>\"   # COMMIT\n   ```\n\n   Push as a separate Bash call, per [`check-before-pushing`](..\u002F..\u002Fshared\u002Fworkflow\u002Fcheck-before-pushing.md)'s \"Keep the commit in its own Bash call\":\n\n   ```bash\n   # `git -C`, not `cd`: whether a separate Bash call keeps the\n   # previous one's directory is unsettled between sessions, so a\n   # relative `cd` breaks in whichever half it did not assume.\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\u002F..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" push -u origin HEAD   # PUSH -- to your fork; PR creation is handled by the post-push verification step below\n   ```\n   **CAUTION:** keeping the push in its own call is what makes the commit durable before anything can refuse the push.\n   If you do chain them and the call is **denied**, *nothing* was committed -- verify with `git status` \u002F `git log` before any `git reset --hard`, or you'll silently discard the still-uncommitted edits.\n\n   **After the PR merges**, remove the worktree so it doesn't accumulate:\n   `git -C \"$repo\" worktree remove \"..\u002Fai-config-worktrees\u002F\u003Cbranch>\"` (the\n   `post-merge` skill's own tidy step does this automatically).\n\n   **After every push in UMS, verify PR state for the current branch in the intended base repo.**\n   `gh pr list --head \u003Cowner>:\u003Cbranch>` silently returns empty for an owner-qualified head ---\n   it only matches a bare branch name, even when a matching PR genuinely exists\n   (verified directly: `gh pr list --head \u003Cowner>:ums-pr635-lessons` returned `[]` against a real open PR on that exact branch,\n   while `gh pr list --head ums-pr635-lessons` found it).\n   Query the REST API instead, whose `head` filter does honor the owner-qualified form:\n   `gh api --method GET \"repos\u002F\u003Cupstream-owner>\u002F\u003Crepo>\u002Fpulls\" -f \"head=\u003Chead-owner>:\u003Ccurrent-branch>\" -f \"state=open\" --jq '.[] | {number, url, state}'`\n   (for `dem-extra1\u002Fai-config`, that is `gh api --method GET \"repos\u002FMorrison-Lab\u002Fai-config\u002Fpulls\" -f \"head=dem-extra1:\u003Ccurrent-branch>\" -f \"state=open\" ...`).\n   If no open PR exists and upstream is accessible,\n   open it as a cross-fork PR immediately with an explicit title and body.\n   Do not pause for draft approval:\n   UMS updates are the durable record of a completed learning,\n   and the PR supplies the reviewable handoff.\n   Bare `gh pr create` without `--fill`\u002F`--title`\u002F`--body` prompts interactively and can hang a headless session:\n\n   ```bash\n   gh repo view \"\u003Cupstream-owner>\u002F\u003Crepo>\" --json defaultBranchRef \\\n     -q .defaultBranchRef.name   # discover the base -- don't hard-code main\n   gh pr create --repo \"\u003Cupstream-owner>\u002F\u003Crepo>\" --base \"\u003Cdiscovered-default-branch>\" \\\n     --head \"\u003Chead-owner>:\u003Ccurrent-branch>\" \\\n     --title \"ums: \u003Csummary>\" --body-file \u002Ftmp\u002Fums-pr-body.md \\\n     --reviewer \u003Creviewer>\n   ```\n\n   If upstream is not accessible in-session, push and explicitly hand off that\n   upstream PR creation is still required.\n\n   **Project-specific items** (a convention or gotcha tied to one repo we\n   own): commit to *that* repo's own agent docs (`CLAUDE.md`,\n   `.github\u002Fagents\u002F*.md`, `.github\u002Finstructions\u002F*.md`,\n   `.github\u002Fcopilot-instructions.md`, or checked-in `.claude\u002Fmemories\u002F`) via a branch + PR in\n   that repo --- not ai-config.\n   Discover its path the same way,\n   `cd`-ing into that repo's own checkout instead of the ai-config one,\n   then follow the same branch\u002Fcommit\u002Fpush\u002FPR steps above,\n   substituting that repo's own default branch for every `main`\u002F`origin main` reference above\n   (don't hard-code `main` --- a project routed here may default to `master` or another name;\n   discover it the same way:\n   `gh repo view \"\u003Cowner>\u002F\u003Crepo>\" --json defaultBranchRef -q .defaultBranchRef.name`).\n   If that repo has no agent-doc infrastructure yet,\n   write to its local Claude project memory\n   (`~\u002F.claude\u002Fprojects\u002F\u003Cproject-path>\u002Fmemory\u002F`) as short-lived staging\n   only --- this is not a durable destination;\n   hand off that the project repo still needs agent-doc infrastructure added (via a PR)\n   and the staged memory migrated there.\n   See the checklist item below.\n\n   **Operational checklist (run in order):**\n\n   - [ ] **Preflight:** confirm branch + cleanliness (`git branch --show-current` \u002F `git status --short`)\n   - [ ] **Safe write form:** for any external post with markdown\u002Fbackticks, use file-backed bodies (`--body-file` or `-F \"body=@\u003Cfile>\"`), never inline double-quoted body strings\n   - [ ] **Postcondition:** after push, verify open PR exists in the intended base repo for the head owner\u002Fbranch (`gh api --method GET \"repos\u002F\u003Cupstream-owner>\u002F\u003Crepo>\u002Fpulls\" -f \"head=\u003Chead-owner>:\u003Cbranch>\" -f \"state=open\" --jq '.[] | {number, url, state}'` --- not `gh pr list --head \u003Cowner>:\u003Cbranch>`, which silently returns empty for an owner-qualified head)\n   - [ ] **Recovery signature:** if shell logs `command not found` during a comment\u002Fcreate command,\n     check whichever CLI the failing command actually invoked (`which gh` or `which glab` --- not always `gh`).\n     If `gh` is unavailable in this session (expected in remote\u002Fweb sessions),\n     fall back to the MCP tool mapping in `tool-mappings.md` instead of retrying the CLI ---\n     `tool-mappings.yml` has no `glab` operations, so a missing `glab` has no MCP fallback;\n     hand off or block instead of retrying.\n     If the CLI that failed *is* installed, the likely cause is backtick substitution mangling the body;\n     re-run using a file-backed body and re-check posted content\n\n5. **Report what was updated.** Provide a brief summary table:\n\n   | What | Where | Change |\n   |------|-------|--------|\n   | Poll for new reviews | `iterate\u002FSKILL.md` | Added explicit polling procedure |\n   | glab has no --state flag | `\u002Fmemories\u002Fgitlab.md` | New bullet |\n\n## What to look for (checklist)\n\n- [ ] Did I follow a skill but miss a step? → Update the skill\n- [ ] Did the user correct my behavior? → Encode as preference + skill update\n- [ ] Did I discover a tool quirk? → the matching topical file under\n  `\u002Fmemories\u002F` (`memories\u002FMEMORY.md` lists the current set; `tools.md` when\n  it fits none of them)\n- [ ] Did I learn a debugging pattern? → `\u002Fmemories\u002Fdebugging.md`\n- [ ] Did I create a *new* file under `\u002Fmemories\u002F`? → register it in\n  `memories\u002FMEMORY.md` as an index entry\n\n- [ ] Did I discover a repo convention for a repo **we own** that has checked-in\n  agent docs? → put it IN that repo (its `CLAUDE.md`, `.github\u002Fagents\u002F*.md`,\n  `.github\u002Finstructions\u002F*.md`, `.github\u002Fcopilot-instructions.md`, or checked-in\n  `.claude\u002Fmemories\u002F`),\n  via a PR, so the whole team and every `@claude` session there sees it. Do NOT\n  keep repo-specific notes in ai-config (`memories\u002Frepo\u002F` is retired). For a repo\n  without agent-doc infrastructure yet, write to this session's own local\n  project-memory mechanism (Claude Code: `~\u002F.claude\u002Fprojects\u002F\u003Cproject-path>\u002Fmemory\u002F`\n  — a non-Claude session should use whatever the equivalent local staging\n  location is for its own agent) as short-lived staging only — hand off that a\n  PR adding agent docs to that repo is still required.\n- [ ] Did the user express a new preference? → `\u002Fmemories\u002Fpreferences.md`\n- [ ] Did a workflow emerge that could be a new skill? → run `spot-skill-opportunities`\n  to judge whether it's genuinely recurring, then `skill-builder` to create it\n- [ ] Did a heavy skill's fan-out step need a dedicated read-only worker persona\n  (like `dependency-auditor` \u002F `hallucination-detector` \u002F `community-demand-scout`),\n  rather than just a new skill? → run `agent-builder` to scaffold\n  `.claude\u002Fagents\u002F\u003Cname>.md`\n- [ ] Are there existing skills that reference outdated info? → Fix them\n- [ ] Has `learn-staging.md` accumulated entries since the last\n  `promote-memory` run? → fold in a `promote-memory` pass now.\n- [ ] Did I edit one step's scope without updating sibling steps in the same file? →\n  Search the file for all enumerations of the changed category and make them consistent.\n- [ ] Did I add a shared-procedure step to one skill but not to sibling skills? →\n  Grep sibling skills for the same action and add the step there too.\n- [ ] Did I change how a skill describes its relationship\u002Fcontrast to a sibling\n  skill (e.g. \"X is passive, Y is explicit\")? → Grep the sibling skill for its\n  own mirrored description of that same relationship and update it too — a\n  one-directional fix leaves the sibling's docs contradicting the new\n  behavior. (Caught by `@claude` review on ai-config#439: `ums\u002FSKILL.md`'s\n  passive-vs-active contrast with `record-learnings` was fixed, but\n  `record-learnings\u002FSKILL.md`'s own mirrored line describing `ums` as \"the\n  explicit ... counterpart\" was missed until review flagged it as a\n  follow-on.)\n\n## Relationship to record-learnings and staged capture\n\n- `record-learnings` = records individual facts in place, in the moment they arise\n- `ums` = a reflective, full-context sweep — survey what accumulated, categorize it, and persist it all in one committed pass\n\nBoth write to the same destinations. `ums` fires proactively, as soon as a\nlearning worth saving shows up, rather than waiting to catch up later; the\n`\u002Fclear` trigger is only a backstop for anything that slipped through.\n\n`spot-skill-opportunities` is the standing, continuous version of this\nskill's \"did a workflow emerge that could be a new skill?\" checklist item —\nit runs the recognition judgment call live, in the moment, instead of only\nat this checkpoint. `agent-builder` is the sibling construction step for the\nother checklist item above — a recurring fan-out worker persona rather than a\nnew user-invocable skill.\n\n`learn`\u002F`promote-memory` are a staged alternative for the uncertain case:\n`record-learnings` and this skill both write directly to committed memory\nthe moment something looks worth remembering, which is right when you're\nconfident. When you're not — a candidate whose generality or evidence isn't\nsolid yet — `learn` stages it instead, and a `promote-memory` pass (which a\n`ums` run can fold in, or run standalone) reviews staged candidates before\nthey land in committed memory. Neither replaces the direct-write path; they\nadd a review gate for the cases that need one.\n\n## Anti-patterns\n\n- ❌ Saying \"I'll remember that\" without actually writing it down\n- ❌ Updating memories but not pushing skill changes to origin\n- ❌ Recording vague lessons (\"be more careful\") instead of specific ones\n  (\"always poll for new review after pushing --- check commit SHA matches\")\n- ❌ Skipping step 3's dupe check and creating duplicates --\n  specifically, reading only the region you're appending to instead of\n  grepping the corpus for the subject\n- ❌ Updating only preferences when a skill also needs the fix\n- ❌ `git add -A` --- it sweeps unrelated in-flight edits (the user's work, other\n  draft skills) into your commit\u002FPR. Stage the specific files you touched.\n- ❌ Creating `memories\u002Frepo\u002F\u003Crepo>.md` for any repo --- this pattern is retired.\n  Put repo-specific lore in the repo's own agent docs (`.github\u002Fagents\u002F`,\n  `CLAUDE.md`, `.github\u002Finstructions\u002F`, `.github\u002Fcopilot-instructions.md`, or\n  checked-in `.claude\u002Fmemories\u002F`) via a PR;\n  if the repo has no agent-doc infrastructure yet, this session's own local\n  project-memory mechanism (Claude Code: `~\u002F.claude\u002Fprojects\u002F\u003Cproject-path>\u002Fmemory\u002F`\n  --- substitute the equivalent for a non-Claude agent) is short-lived staging\n  only --- hand off that a PR adding those agent docs is still required.\n  See the checklist item above and `memories\u002Fpreferences.md` for the full rule.\n- ❌ Naming a tool, flag, or API identifier that appears **nowhere else in the\n  corpus** without anchoring it somewhere checkable. A lone mention reads\n  identically whether it is correct or hallucinated, so a later session has\n  nothing to verify it against --- and the guidance is only actionable if the\n  name is right. When the identifier is a cross-model tool, add it to\n  `tool-mappings.yml` (then regenerate) rather than leaving the memory bullet\n  as its only home; otherwise cite where you confirmed it. Having *used* it\n  successfully in the session you're writing up is good evidence, but that\n  evidence dies with the session. (ai-config#727: `mcp__github__list_commits`\n  was flagged in review as unanchored; it was genuinely verified by use, and\n  the fix was registering it as the `LIST_COMMITS` operation.)\n- ❌ Writing up an incident from **recall** rather than re-deriving its\n  figures and its mechanism from the artifacts.\n  The artifacts are still there --- that they are still there is exactly why\n  the entry is worth writing now.\n  The bullet above covers an identifier that appears nowhere else;\n  this covers an entry whose identifiers are all real,\n  and whose *quantities* and *causal claim* are invented.\n  It is the harder case, because having **witnessed** the incident feels like\n  evidence,\n  so nothing about composing the entry resembles guessing.\n  Re-read the commit, re-run the command, re-open the issue,\n  and quote what they say ---\n  [`verify-the-right-artifact.md`](..\u002F..\u002Fshared\u002Fworkflow\u002Fverify-the-right-artifact.md)\n  states the general form, that a figure a reader can re-derive beats one you\n  assert.\n  (ai-config#2637: a 37-line entry recording a reformatter incident from\n  earlier the same session drew eight blocking findings from an adversarial\n  self-review --- a count worth attributing, since the PR's own bot review\n  raised one.\n  Nearly every factual claim in the entry was false.\n  \"Three pre-existing paragraphs\" was one,\n  \"200 to 350 characters\" measured 178--268,\n  and \"from 1 to 11\" was 0 to 11.\n  The mechanism was wrong too:\n  the entry blamed `--write` for reflowing whole files,\n  when `--write` has been diff-scoped since #951 and `--all` is what widens\n  it, so the prescribed remedy would not have prevented the churn the entry\n  was written about.\n  The passage was withdrawn rather than patched.\n  The same PR's other half, which survived, carried the matching error in its\n  citations: \"#1373 recorded 47% over\" was 487%, read off that issue's title\n  while its own console block sat below it ---\n  and the passage citing it was citing #2626, whose subject is reading a\n  summary in place of its source.)\n- ❌ Inserting a new bullet into any memory file with nested lists (including\n  `github-actions.md`, `preferences.md`) without checking the surrounding indentation\n  first. These files mix 0-indent top-level bullets with 2-\u002F4-indent sub-bullets and\n  multi-paragraph continuations; a new top-level bullet dropped in the middle\n  of an existing parent's sub-list re-parents whatever follows it in Markdown\n  (a sibling sub-bullet silently becomes this new bullet's child). Before\n  committing an insertion, re-read the few lines immediately above and below\n  the insertion point and confirm the indentation still matches what it did\n  before — or place the new bullet after the complete enclosing list instead\n  of inside it. (Caught by `@claude` review on ai-config#335: a new 0-indent\n  bullet landed between two sibling sub-bullets of an existing parent,\n  breaking the nesting.)\n- ❌ Patching a sentence the entry's point does not need, round after round.\n  When successive review rounds find defects in mechanism prose no reader\n  acts on, delete the prose rather than repair it; the tell is the third\n  round on the same paragraph (ai-config#3193: five successive commits,\n  `1fff7e63` to `4af1f1ea`, each re-patched the same protocol-mechanism\n  sentences, which the entry's Do\u002FDon't never used and `e91dda59` deleted;\n  the deleted paragraphs were not restored).\n  The same shape recurs when a fix round appends prose narrating its own\n  fixes: that prose is fresh unmeasured text, so a round that fixes N\n  findings and adds a paragraph about them adds new claims to refute\n  (ai-config#3202: the three notebook entries narrating rounds 1 to 3 were\n  deleted rather than patched at `48380505`, and the summary entry that\n  replaced them kept being re-edited, its round count rebound to each new\n  head, until the merged file's \"As of `75bc0fc2`, the head round 13\n  reviewed\").\n  Write the fix with no narration;\n  ai-config#3203 proposes the same brief for a fix loop's fixer.\n\n## Proactive hook compliance\n\n- **`remind-ums-after-error.py`**: Prompt-injection hook that fires\n  when an admitted mistake has no subsequent memory or skill modification.\n  Satisfy it by executing `ums` immediately upon acknowledging an error.\n- **`remind-ums-on-scrutiny.py`**: Injects a reminder when a review was read\n  or a questioned claim was corrected without a recorded UMS pass.\n- **`remind-learn-from-review.py`**: Reminds when an accepted reviewer finding\n  has no accompanying learning or guard recorded.\n- **`no-mistake-without-a-hook.py`**: Stop guard and reminder that blocks after an admitted,\n  mechanizable mistake until a hook (`hooks\u002F\u003Cname>.py`), test (`hooks\u002Ftest-\u003Cname>.py`),\n  and manifest binding (`hooks\u002Fhooks.json`) are authored.\n","# UMS — Update Memories and Skills\n\nActively review recent session context and update all relevant memory files\nand skill definitions to capture what was learned. Unlike `record-learnings`\n(which records individual facts in place as they arise), UMS is a reflective\ncheckpoint: survey what accumulated, categorize it, and persist it all in one\ncommitted pass.\n\n## When this fires\n\n- **As soon as a learning worth saving shows up** — a corrected mistake, a\n  new preference, a tool quirk, a workflow gap. This is the primary trigger:\n  run UMS right then, interleaved with the main work, instead of batching\n  learnings for a wrap-up step at the end. Don't wait for the task to finish\n  or for `\u002Fclear` to accumulate a backlog — and don't gate it on approval or\n  on a PR merging: capture the learning the moment it appears, even while the\n  PR that taught it is still open and unreviewed.\n  **A user correction is a mandatory immediate trigger.** Persist the lesson\n  before resuming the main task; never wait for the user to invoke UMS or\n  remind you a second time.\n  **User profanity or frustration is an urgent trigger.**\n  It signals a severe mistake, broken assumption, or dropped preference\n  requiring immediate diagnosis, repair, and learning\n  (see [`user-profanity-signal`](..\u002F..\u002Fshared\u002Fworkflow\u002Fuser-profanity-signal.md)).\n- **When you read a review of your work, receive critical feedback on it,\n  or a questioned claim turns out to be wrong.**\n  The trigger is the scrutiny, not Address, not a clean verdict, and not\n  a first-person admission.\n  \"Are you sure about that?\" is the questioning case: check the claim, and\n  if it was wrong, run UMS --- answering with the corrected fact is not\n  the pass.\n  Questioning alone does not owe a pass when the claim holds.\n  See\n  [`run-ums-proactively`](..\u002F..\u002Fshared\u002Fworkflow\u002Frun-ums-proactively.md).\n- **When a PR reaches a clean review verdict** -- the checkpoint the\n  `ardi` loop exits on, and the backstop if the user-correction trigger\n  or the scrutiny trigger above was skipped.\n  Run the pass there rather than at the merge: the merge is human-gated and\n  may land long after this session ends, while the verdict is the moment the\n  review lifecycle has finished teaching.\n- **Even when a new request arrives at that same moment** -- the mechanism\n  that actually skips the user-correction trigger, the scrutiny trigger,\n  and the clean-verdict checkpoint.\n  A merge or clean verdict is when you report back, so it is also when the\n  next instruction lands, and that instruction reads as the live task while\n  the owed pass quietly evaporates: never refused, never deferred out loud,\n  just never performed.\n  A new request does not cancel a checkpoint.\n  Run the pass first (it is short), or say in the same reply that it is owed\n  and when it will run.\n  Deferring out loud is fine; dropping it silently is the failure.\n  Watch for it too when a skill *ends* in a UMS step (`post-merge`, `ardi`,\n  `wrap-up`): reporting that skill complete asserts its final step ran, so\n  confirm the pass happened rather than only the steps before it.\n  Loading the skill is not confirmation.\n  A valid no-change pass must still complete the context scan and, for every candidate, categorize it and grep the destination's full `memories\u002F` directory plus the relevant skill and shared-workflow files;\n  report the candidates and searches instead of merely asserting that no update was needed. (Recurrence, 2026-09-14: after a merge, the skill was loaded and one narrow grep was run, but the merge was reported wrapped up with \"UMS review found no additional durable memory update needed\";\n  the user's \"what about ums?\" exposed that the actual pass had never run.)\n- User says \"ums\", \"update memories and skills\", \"record what we learned\"\n- **At the start of `\u002Fclear`** — a backstop, not the primary trigger: catch\n  anything accumulated since the last proactive pass before context is lost\n- After a workflow reveals a gap (e.g., a skill was followed but missed a\n  step, or a preference wasn't encoded)\n- When the user says \"did you update memories?\" (the answer should be \"let\n  me do that now\")\n- **Before ending a turn to wait on anything** --- a subagent,\n  a long-running background process, CI, a review round,\n  or an answer from the user.\n  Run the pass before the turn ends,\n  not once the wait turns out to be long:\n  a wait's length is not knowable when it begins,\n  and the learnings sit in conversation state until it ends.\n  A dispatched subagent or background job is the case\n  where the pass runs alongside the wait rather than delaying it,\n  so don't let a real wait sit fully idle.\n  The pass is owed at the first pause\n  and again only once new learnings accumulate,\n  rather than once per wait or once per re-arm of a timer.\n  See\n  [`run-ums-proactively`](..\u002F..\u002Fshared\u002Fworkflow\u002Frun-ums-proactively.md).\n\n## Procedure\n\n1. **Scan recent context.** Review the conversation for:\n   - Mistakes made and corrected (skill gaps)\n   - New preferences expressed by the user\n   - Tool quirks discovered\n   - Workflow steps that were missing or unclear in existing skills\n   - Debugging insights\n   - Codebase conventions discovered\n\n   *(When delegating UMS to a subagent, prefer **conversation-inheriting dispatch**\n   (Agent `subagent_type: \"fork\"` or `\u002Fsubtask` in Claude Code, or providing the transcript log path in clean-slate harnesses)\n   so the subagent surveys conversation history directly without manual serialization;\n   see [`use-subagents`](..\u002F..\u002Fshared\u002Fworkflow\u002Fuse-subagents.md).)*\n\n2. **Categorize each learning.** For each item, decide:\n   - Is it a **skill update**? (workflow step missing, procedure unclear)\n   - Is it a **memory note**? (tool quirk, preference, debugging insight)\n   - Is it **both**? (general guidance → update skill AND preferences)\n   - Is it already recorded? (grep before writing -- avoid duplicates)\n   - Is it **cross-project or project-specific**? (`memories\u002Fpreferences.md`'s\n     \"Memory and skill storage\" rule: cross-project lessons commit to\n     `Morrison-Lab\u002Fai-config`; a convention\u002Fgotcha tied to one repo we own\n     commits to *that* repo's own agent docs instead --- see the checklist\n     item below for where. This changes step 4's target, not just the\n     content.)\n\n3. **Apply updates.** For each item:\n   - Read the target file first (skill or memory) to understand current state\n   - **Grep the corpus for the item's specific subject** -- the tool name, the\n     API call, the error string -- before appending anything.\n     Reading the region you're editing is not enough: a topical memory file\n     runs to hundreds or a thousand-plus lines, so an existing entry on the\n     same subject can sit far away in an unrelated cluster and never enter\n     your view.\n     Grep [`skill-builder`](..\u002Fskill-builder\u002FSKILL.md) step 0's path list\n     rather than one file, and rather than only `memories\u002F`:\n     ```bash\n     (\n       repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || git rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n       test -f \"$repo\u002FCLAUDE.md\" && test -d \"$repo\u002Fshared\" || { echo \"not an ai-config checkout: $repo\" >&2; exit 1; }\n       cd \"$repo\" && grep -rilIF -- \"\u003Csubject>\" skills\u002F scripts\u002F hooks\u002F shared\u002F memories\u002F CLAUDE.md\n     )\n     ```\n     The query runs over the files on disk,\n     so an entry that exists only on a branch not checked out there is out of reach\n     (see the unmerged-PR section of [`grep-is-not-coverage`](..\u002F..\u002Fshared\u002Fworkflow\u002Fgrep-is-not-coverage.md)).\n     `-F` matches the subject as a fixed string,\n     so an error string carrying `[`, `.`, or `*` is searched for as written;\n     `-I` skips binary files, bytecode caches included,\n     which a plain `grep -r` would otherwise report as hits.\n     A rule can be owned by a `shared\u002F` fragment or a skill as easily as by a memory,\n     and a `memories\u002F`-only grep stays outside those paths.\n     When the grep finds an existing entry on the subject, extend that entry in place;\n     don't add a second bullet.\n     (ai-config#689: a `list_workflow_runs` cost bullet went in next to the\n     related `get_check_runs` guidance while an entry on the same tool already\n     sat ~2000 lines below in the write-access cluster -- caught by the review\n     bot, not by the author.)\n   - **Run `python3 scripts\u002Fcheck-memory-file-size.py` before writing the\n     append, and read its warning band, not only its pass\u002Ffail line.**\n     The band names every memory file near the cap and how many lines each\n     has left (ai-config#3102), so a file with almost no\n     headroom is knowable here, while the entry can still be re-wrapped or the\n     file split, rather than by tripping the gate in step 4 once the append is\n     written.\n     Read each listed file's headroom, not its membership: the band opens 100\n     lines below the cap at the shipped default, so most of it is room rather\n     than a warning.\n     - **Do:** read the reported headroom of the file the entry topically\n       belongs in, and recover lines or split that file when its headroom does\n       not comfortably cover the entry.\n     - **Don't:** pick the destination by headroom rather than by subject,\n       or redirect or split on band membership alone --- a file with most of\n       the band still ahead of it can take this entry.\n   - **When the target memory file is already at the cap\n     `scripts\u002Fcheck-memory-file-size.py` reports**,\n     recover lines (re-wrap or drop) or split the file.\n     A fold has two shapes and neither escapes every gate: a new source\n     line trips `scripts\u002Ftest_check_memory_file_size.py`, while folding\n     the sentence into an existing line leaves the count flat but makes\n     that line a changed line the new-line-breaks gate can flag.\n     A net-positive append fails\n     `scripts\u002Ftest_check_memory_file_size.py`\n     even when every new sentence is a real lesson\n     (5th occurrence, 2026-10-07 on `memories\u002Fmistake-patterns.md`, PR #4348:\n     `main` sat at 1244 lines with 6 lines of headroom,\n     and appending Pattern 62 pushed the file to 1261 lines,\n     breaching `scripts\u002Fcheck-memory-file-size.py --strict` in CI `validate.yml`;\n     files within 10 lines of the 1250-line limit must be split or condensed,\n     not appended past the cap;\n     4th occurrence, 2026-09-09 on `memories\u002Fmistake-patterns.md`,\n     found by a scheduled PR-sweep session rather than by a push: `main` sat\n     exactly at the cap, 1250 lines \u002F 61 `## Pattern` headings, at the exact\n     value `--max-lines` defaults to, with zero headroom -- confirmed via\n     `python3 scripts\u002Fcheck-memory-file-size.py --strict` (exit 0, \"0 lines\n     of headroom\") and independently via PR #3386's head (`3f58d9b6`, 1275\n     lines \u002F 62 headings) failing `validate`'s size check.\n     The consequence is not scoped to whichever PR crosses the line: with the\n     file already full, every other open PR that appends a pattern --\n     unrelated in content, no larger than any prior append -- fails the same\n     check the moment it is pushed, which is easy to misread as a defect in\n     that PR rather than as pre-existing headroom exhaustion.\n     The split is tracked in ai-config#3340, filed 2026-09-07 and still open;\n     check it before re-filing.\n     Prior: `memories\u002Fpreferences.md` ai-config#2262 (3rd, 2026-08-25:\n     `origin\u002Fmain` sat exactly at the cap, 1200 lines as that cap then stood,\n     and a +5-line append reddened `validate`);\n     `shared\u002Fwriting\u002Fsemantic-line-breaks.md` ai-config#1291;\n     `shared\u002Fworkflow\u002Freview-verdict-pitfalls.md` ai-config#811).\n   - **When the file to split enforces its own numbering invariant,\n     \"move whole sections\" is not automatic.**\n     `memories\u002Fmistake-patterns.md`'s `## Pattern N:` headings are checked\n     by `scripts\u002Fcheck-mistake-patterns.py`,\n     which requires the integers to run `1..K` in file order with no gap\n     (a lettered sub-pattern like `5c` follows its base entry\n     and advances by letter).\n     Lifting a non-contiguous subset out ---\n     exactly what ai-config#3340 proposes\n     (Patterns 21, 43, 50, 51, 52, 55) ---\n     opens a gap the checker rejects\n     unless every later heading is renumbered,\n     or the lifted headings are kept as stub pointers in place.\n     Every citation by number then needs the same repoint:\n     at least 27 files outside `memories\u002Fmistake-patterns.md` itself\n     cite a pattern by number\n     (`grep -rlE 'Pattern [0-9]+[a-z]?\\b' --include='*.md' --include='*.py' .`,\n     filtered for two unrelated numbered-list false positives ---\n     `skills\u002Fcli\u002Freferences\u002Fconditions.md`'s own \"Pattern 1\u002F2\u002F3\u002F4\"\n     and `skills\u002Fdetect-informal-definitions\u002FSKILL.md`'s\n     \"Pattern 1\"\u002F\"Pattern 2\"\u002F\"Pattern 3\" ---\n     and one synthetic test fixture,\n     `scripts\u002Ftest_check_mistake_patterns.py`,\n     which types pattern numbers that never existed to exercise the regex).\n     The file also carries its own in-file directional cross-references\n     (\"Pattern 25 above\" at line 544, \"Pattern 20 below\" at line 451,\n     seven total)\n     that a move falsifies without breaking any link a grep would catch.\n     - **Do:** before moving any `## Pattern N:` section out of\n       `mistake-patterns.md`,\n       grep the whole repo for `Pattern N`\n       and repoint every genuine hit, including in-file \"above\"\u002F\"below\" wording,\n       after excluding unrelated numbered-list prose\n       by reading each match rather than trusting the grep's raw file count.\n     - **Do:** either renumber every heading after a lifted gap\n       so `check-mistake-patterns.py` still reads `1..K` with no gap,\n       or leave a stub `## Pattern N:` heading pointing at the new file,\n       rather than deleting the number outright.\n     - **Don't:** move a non-contiguous subset of patterns to a satellite file\n       on the strength of `check-memory-file-size.py`'s own generic\n       \"move whole sections, repoint inbound references\" advice ---\n       that advice is about the size gate alone\n       and says nothing about the separate contiguity gate\n       `check-mistake-patterns.py` enforces.\n     - **Don't:** treat a raw `grep -rl` file count as the citation count to repoint ---\n       a numbered-heading pattern like `Pattern N` recurs in unrelated prose\n       elsewhere in the repo,\n       and counting those inflates the sweep without finding anything to fix.\n   - **When step 2 routed the item to a repo other than ai-config, grep both\n     corpora.**\n     The query above searches an ai-config checkout,\n     so run a second pass in the destination repo, over that repo's own doc paths ---\n     a repo-local entry can otherwise duplicate or contradict a fragment\n     nobody thought to search from that repo.\n     See\n     [`grep-is-not-coverage`](..\u002F..\u002Fshared\u002Fworkflow\u002Fgrep-is-not-coverage.md)'s\n     \"Searching the wrong corpus is the same error with no grep in it\".\n   - **When the subject grep finds an existing entry covering this class, record the\n     recurrence on the existing entry, not just the new fact.**\n     The **Grep the corpus** bullet above already says to extend in place\n     rather than add a sibling;\n     what is missing is the count.\n     Write it on the entry -- \"3rd occurrence, 2026-08-16\", with a pointer to\n     each prior record -- so the entry carries evidence about whether the\n     written rule is actually holding.\n\n     The count has a consumer that already exists and currently has nothing to\n     read.\n     [`deterministic-tools`](..\u002F..\u002Fshared\u002Fprinciples\u002Fdeterministic-tools.md)\n     names the third occurrence as the moment a recurring judgment task becomes\n     a tool, and\n     [`learn-from-review-findings`](..\u002F..\u002Fshared\u002Fworkflow\u002Flearn-from-review-findings.md)\n     asks of every accepted finding whether it is algorithmatizable -- but\n     nothing in the corpus counts, so that trigger fires on recollection or not\n     at all.\n     A rule on its third recurrence is a rule demonstrably not holding, which\n     is the argument for a hook or a check rather than for a sharper sentence.\n\n     A recurrence note is also a duplication signal for\n     [`find-overlap`](..\u002Ffind-overlap\u002FSKILL.md) and\n     [`consolidate-memory`](..\u002Fconsolidate-memory\u002FSKILL.md), since one class\n     recorded twice under different wording is exactly the near-duplicate a\n     phrase-similarity pass under-detects.\n     The reverse reading -- an entry that has never recurred and is never cited\n     is a retirement candidate -- has **no** consumer today, so treat it as a\n     property the count makes available rather than as a step anything runs.\n   - Make the edit --- concise bullet points, not prose\n   - If updating a skill: the change should be specific enough that following\n     the skill next time would avoid the mistake\n\n4. **Commit and push --- via a branch + PR, not direct to `main`, in whichever\n   repo step 2 routed the item to.**\n\n   If the work will dispatch an expensive external action from a pinned commit\n   (such as a release, deployment, or batch computation), create, push, and\n   open the PR **before** dispatching it. The PR is the reviewable record of the\n   exact SHA that performed the action; opening it afterward is too late.\n\n   **Do this in an isolated `git worktree`, not the shared ai-config checkout\n   directly** -- `memories\u002Fpreferences.md`'s \"Run a local session in an\n   isolated git worktree by DEFAULT\" rule applies here too.\n   The shared checkout is routinely in concurrent use by other sessions also\n   running UMS; a `git checkout \u003Cbranch>` from another session mid-command\n   can silently redirect *your* `git commit`\u002F`git push` onto *their* branch\n   (and vice versa), and a local `git status`\u002F`git log` read moments later\n   can already reflect a third session's activity, not your own.\n   Every code block below creates (or reuses) a worktree first, then runs\n   every `git add`\u002F`commit`\u002F`push` from inside it -- never `cd` straight\n   into the shared checkout itself to make a change.\n\n   **Run the repo's own gates on the files you touched before the commit**,\n   since a UMS PR fails CI on the same checks as any other:\n   `python3 scripts\u002Fcheck-memory-file-size.py --strict` (a memory file over\n   1250 lines fails; split it, as `memories\u002Fmarkdownlint.md` was split from\n   `tools.md` on 2026-09-01 when a UMS append crossed the budget),\n   `NLB_BASE_REF=origin\u002Fmain python3 scripts\u002Fvendor\u002Fgha-check-new-line-breaks.py`,\n   `python3 scripts\u002Fcheck-links.py`, and `markdownlint` on the changed files.\n\n   `check-memory-file-size.py` prints its warning band here too, but this run\n   is the pass\u002Ffail one: the band is actionable in step 3, before the append is\n   written, and by now the append already exists.\n\n   **If a push is rejected non-fast-forward:** fetch first and diff before\n   assuming a real conflict -- the branch may have picked up another\n   session's commit that needs separating out (`git revert \u003Ctheir-commit>`)\n   rather than force-pushing over it.\n   Verify the PR's real, current content via `gh api\n   repos\u002F\u003Cowner>\u002F\u003Crepo>\u002Fpulls\u002F\u003CN>\u002Ffiles` or `git ls-remote`\u002F`git show\n   origin\u002F\u003Cbranch>:\u003Cpath>` (the GitHub-side truth), not the local checkout,\n   which may have already moved again.\n   (ai-config#748: a UMS commit collided with another concurrent session's\n   UMS commit on a shared branch name this way -- both sessions' content\n   ended up interleaved on one branch before separating back out, resolved\n   without data loss only because both sides fetched-before-pushing and\n   diffed before force-acting.)\n\n   **Cross-project items** (skills, cross-project memory notes): both live in\n   the ai-config repo. Discover its path with\n   `${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}` — point\n   `-C` at a **skill subdir** (any one), not the `~\u002F.claude\u002Fskills` parent.\n   `bootstrap.sh` may symlink skills *per-child* into a real `~\u002F.claude\u002Fskills`\n   directory (cloud\u002Fweb sessions pre-populate it), so the parent itself isn't a\n   symlink into the repo and `git -C` there fails with \"not a git repository\";\n   a child like `…\u002Fskills\u002Fums` follows the symlink into the repo. (Both beat the\n   older `dirname \"$(readlink …)\"`, which resolves only one symlink hop.) Never\n   leave ANY changes (skills, memories, etc.) as local-only uncommitted edits.\n   Run **one** of the two paths below — not both:\n\n   **Stage only the files you actually edited — NEVER `git add -A`.** The\n   working tree often holds unrelated in-flight edits (the user's own UMS\n   commits, another skill being drafted); `git add -A` sweeps those into your\n   commit and onto your PR, where they bloat the review and extend the cycle.\n   List the specific paths instead. Then **`git status` to confirm only your\n   intended files are staged** — if something unexpected is there, the working\n   tree had in-flight work; unstage it rather than bundling it. (Avoid\n   `git add -p` here: it needs a terminal and hangs in non-interactive sessions.)\n\n   Every path below starts by resolving `$repo`, the shared checkout's path\n   (read-only -- discovering the path doesn't touch the shared working\n   directory), then creates or reuses a **worktree** off it and does every\n   write from inside that worktree instead.\n\n   *Already on the open PR's branch* (e.g. mid-ARDI): reuse a worktree for\n   it, creating one if this is the first push in the worktree-ified flow.\n   ```bash\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   wt=\"..\u002Fai-config-worktrees\u002F\u003Cbranch>\"\n   git -C \"$repo\" worktree add \"$wt\" \"\u003Cbranch>\" 2>\u002Fdev\u002Fnull || true   # no-op if it already exists\n   cd \"$wt\"\n   git add \"skills\u002F\u003Cname>\u002FSKILL.md\" \"memories\u002F\u003Cfile>.md\"   # the files you touched\n   git commit -m \"ums: \u003Cbrief summary>\"   # COMMIT\n   ```\n\n   Push as a separate Bash call, per [`check-before-pushing`](..\u002F..\u002Fshared\u002Fworkflow\u002Fcheck-before-pushing.md)'s \"Keep the commit in its own Bash call\":\n\n   ```bash\n   # `git -C`, not `cd`: whether a separate Bash call keeps the\n   # previous one's directory is unsettled between sessions, so a\n   # relative `cd` breaks in whichever half it did not assume.\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\u002F..\u002Fai-config-worktrees\u002F\u003Cbranch>\" push origin HEAD   # PUSH\n   ```\n\n   *No PR yet:* branch off main first — a direct-to-main push is denied by\n   auto-mode and bypasses review.\n\n   *Same-repo case* (this checkout's `origin` IS the repo you're targeting):\n   ```bash\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\" fetch origin main   # FETCH\n   git -C \"$repo\" worktree add -b \"ums-\u003Ctopic>\" \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" origin\u002Fmain   # CREATE_BRANCH\n   cd \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\"\n   git add \"skills\u002F\u003Cname>\u002FSKILL.md\" \"memories\u002F\u003Cfile>.md\"   # the files you touched\n   git commit -m \"ums: \u003Cbrief summary>\"   # COMMIT\n   ```\n\n   Push as a separate Bash call, per [`check-before-pushing`](..\u002F..\u002Fshared\u002Fworkflow\u002Fcheck-before-pushing.md)'s \"Keep the commit in its own Bash call\":\n\n   ```bash\n   # `git -C`, not `cd`: whether a separate Bash call keeps the\n   # previous one's directory is unsettled between sessions, so a\n   # relative `cd` breaks in whichever half it did not assume.\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\u002F..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" push -u origin HEAD   # PUSH -- PR creation is handled by the post-push verification step below\n   ```\n\n   *Cross-fork case* (this checkout's `origin` is your own fork, not the\n   upstream repo you're targeting): don't branch from a bare `origin\u002Fmain`\n   here -- the fork's `main` can be stale relative to upstream's default\n   branch. Fetch the intended **upstream** repo explicitly (not just look up\n   its default-branch name) and branch the worktree from that fetched ref:\n   ```bash\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   base=\"$(gh repo view \"\u003Cupstream-owner>\u002F\u003Crepo>\" --json defaultBranchRef -q .defaultBranchRef.name)\" \\\n     && git -C \"$repo\" fetch \"https:\u002F\u002Fgithub.com\u002F\u003Cupstream-owner>\u002F\u003Crepo>.git\" \"$base\" \\\n     && git -C \"$repo\" worktree add -b \"ums-\u003Ctopic>\" \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" FETCH_HEAD\n   # chained with && on purpose -- a failed lookup or fetch must stop the\n   # worktree creation, or it silently reuses an older FETCH_HEAD from a\n   # prior fetch, recreating the stale-base problem this block exists to prevent\n   cd \"..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\"\n   git add \"skills\u002F\u003Cname>\u002FSKILL.md\" \"memories\u002F\u003Cfile>.md\"   # the files you touched\n   git commit -m \"ums: \u003Cbrief summary>\"   # COMMIT\n   ```\n\n   Push as a separate Bash call, per [`check-before-pushing`](..\u002F..\u002Fshared\u002Fworkflow\u002Fcheck-before-pushing.md)'s \"Keep the commit in its own Bash call\":\n\n   ```bash\n   # `git -C`, not `cd`: whether a separate Bash call keeps the\n   # previous one's directory is unsettled between sessions, so a\n   # relative `cd` breaks in whichever half it did not assume.\n   repo=\"${CLAUDE_PLUGIN_ROOT:-$(git -C ~\u002F.claude\u002Fskills\u002Fums rev-parse --show-toplevel 2>\u002Fdev\u002Fnull || pwd)}\"\n   git -C \"$repo\u002F..\u002Fai-config-worktrees\u002Fums-\u003Ctopic>\" push -u origin HEAD   # PUSH -- to your fork; PR creation is handled by the post-push verification step below\n   ```\n   **CAUTION:** keeping the push in its own call is what makes the commit durable before anything can refuse the push.\n   If you do chain them and the call is **denied**, *nothing* was committed -- verify with `git status` \u002F `git log` before any `git reset --hard`, or you'll silently discard the still-uncommitted edits.\n\n   **After the PR merges**, remove the worktree so it doesn't accumulate:\n   `git -C \"$repo\" worktree remove \"..\u002Fai-config-worktrees\u002F\u003Cbranch>\"` (the\n   `post-merge` skill's own tidy step does this automatically).\n\n   **After every push in UMS, verify PR state for the current branch in the intended base repo.**\n   `gh pr list --head \u003Cowner>:\u003Cbranch>` silently returns empty for an owner-qualified head ---\n   it only matches a bare branch name, even when a matching PR genuinely exists\n   (verified directly: `gh pr list --head \u003Cowner>:ums-pr635-lessons` returned `[]` against a real open PR on that exact branch,\n   while `gh pr list --head ums-pr635-lessons` found it).\n   Query the REST API instead, whose `head` filter does honor the owner-qualified form:\n   `gh api --method GET \"repos\u002F\u003Cupstream-owner>\u002F\u003Crepo>\u002Fpulls\" -f \"head=\u003Chead-owner>:\u003Ccurrent-branch>\" -f \"state=open\" --jq '.[] | {number, url, state}'`\n   (for `dem-extra1\u002Fai-config`, that is `gh api --method GET \"repos\u002FMorrison-Lab\u002Fai-config\u002Fpulls\" -f \"head=dem-extra1:\u003Ccurrent-branch>\" -f \"state=open\" ...`).\n   If no open PR exists and upstream is accessible,\n   open it as a cross-fork PR immediately with an explicit title and body.\n   Do not pause for draft approval:\n   UMS updates are the durable record of a completed learning,\n   and the PR supplies the reviewable handoff.\n   Bare `gh pr create` without `--fill`\u002F`--title`\u002F`--body` prompts interactively and can hang a headless session:\n\n   ```bash\n   gh repo view \"\u003Cupstream-owner>\u002F\u003Crepo>\" --json defaultBranchRef \\\n     -q .defaultBranchRef.name   # discover the base -- don't hard-code main\n   gh pr create --repo \"\u003Cupstream-owner>\u002F\u003Crepo>\" --base \"\u003Cdiscovered-default-branch>\" \\\n     --head \"\u003Chead-owner>:\u003Ccurrent-branch>\" \\\n     --title \"ums: \u003Csummary>\" --body-file \u002Ftmp\u002Fums-pr-body.md \\\n     --reviewer \u003Creviewer>\n   ```\n\n   If upstream is not accessible in-session, push and explicitly hand off that\n   upstream PR creation is still required.\n\n   **Project-specific items** (a convention or gotcha tied to one repo we\n   own): commit to *that* repo's own agent docs (`CLAUDE.md`,\n   `.github\u002Fagents\u002F*.md`, `.github\u002Finstructions\u002F*.md`,\n   `.github\u002Fcopilot-instructions.md`, or checked-in `.claude\u002Fmemories\u002F`) via a branch + PR in\n   that repo --- not ai-config.\n   Discover its path the same way,\n   `cd`-ing into that repo's own checkout instead of the ai-config one,\n   then follow the same branch\u002Fcommit\u002Fpush\u002FPR steps above,\n   substituting that repo's own default branch for every `main`\u002F`origin main` reference above\n   (don't hard-code `main` --- a project routed here may default to `master` or another name;\n   discover it the same way:\n   `gh repo view \"\u003Cowner>\u002F\u003Crepo>\" --json defaultBranchRef -q .defaultBranchRef.name`).\n   If that repo has no agent-doc infrastructure yet,\n   write to its local Claude project memory\n   (`~\u002F.claude\u002Fprojects\u002F\u003Cproject-path>\u002Fmemory\u002F`) as short-lived staging\n   only --- this is not a durable destination;\n   hand off that the project repo still needs agent-doc infrastructure added (via a PR)\n   and the staged memory migrated there.\n   See the checklist item below.\n\n   **Operational checklist (run in order):**\n\n   - [ ] **Preflight:** confirm branch + cleanliness (`git branch --show-current` \u002F `git status --short`)\n   - [ ] **Safe write form:** for any external post with markdown\u002Fbackticks, use file-backed bodies (`--body-file` or `-F \"body=@\u003Cfile>\"`), never inline double-quoted body strings\n   - [ ] **Postcondition:** after push, verify open PR exists in the intended base repo for the head owner\u002Fbranch (`gh api --method GET \"repos\u002F\u003Cupstream-owner>\u002F\u003Crepo>\u002Fpulls\" -f \"head=\u003Chead-owner>:\u003Cbranch>\" -f \"state=open\" --jq '.[] | {number, url, state}'` --- not `gh pr list --head \u003Cowner>:\u003Cbranch>`, which silently returns empty for an owner-qualified head)\n   - [ ] **Recovery signature:** if shell logs `command not found` during a comment\u002Fcreate command,\n     check whichever CLI the failing command actually invoked (`which gh` or `which glab` --- not always `gh`).\n     If `gh` is unavailable in this session (expected in remote\u002Fweb sessions),\n     fall back to the MCP tool mapping in `tool-mappings.md` instead of retrying the CLI ---\n     `tool-mappings.yml` has no `glab` operations, so a missing `glab` has no MCP fallback;\n     hand off or block instead of retrying.\n     If the CLI that failed *is* installed, the likely cause is backtick substitution mangling the body;\n     re-run using a file-backed body and re-check posted content\n\n5. **Report what was updated.** Provide a brief summary table:\n\n   | What | Where | Change |\n   |------|-------|--------|\n   | Poll for new reviews | `iterate\u002FSKILL.md` | Added explicit polling procedure |\n   | glab has no --state flag | `\u002Fmemories\u002Fgitlab.md` | New bullet |\n\n## What to look for (checklist)\n\n- [ ] Did I follow a skill but miss a step? → Update the skill\n- [ ] Did the user correct my behavior? → Encode as preference + skill update\n- [ ] Did I discover a tool quirk? → the matching topical file under\n  `\u002Fmemories\u002F` (`memories\u002FMEMORY.md` lists the current set; `tools.md` when\n  it fits none of them)\n- [ ] Did I learn a debugging pattern? → `\u002Fmemories\u002Fdebugging.md`\n- [ ] Did I create a *new* file under `\u002Fmemories\u002F`? → register it in\n  `memories\u002FMEMORY.md` as an index entry\n\n- [ ] Did I discover a repo convention for a repo **we own** that has checked-in\n  agent docs? → put it IN that repo (its `CLAUDE.md`, `.github\u002Fagents\u002F*.md`,\n  `.github\u002Finstructions\u002F*.md`, `.github\u002Fcopilot-instructions.md`, or checked-in\n  `.claude\u002Fmemories\u002F`),\n  via a PR, so the whole team and every `@claude` session there sees it. Do NOT\n  keep repo-specific notes in ai-config (`memories\u002Frepo\u002F` is retired). For a repo\n  without agent-doc infrastructure yet, write to this session's own local\n  project-memory mechanism (Claude Code: `~\u002F.claude\u002Fprojects\u002F\u003Cproject-path>\u002Fmemory\u002F`\n  — a non-Claude session should use whatever the equivalent local staging\n  location is for its own agent) as short-lived staging only — hand off that a\n  PR adding agent docs to that repo is still required.\n- [ ] Did the user express a new preference? → `\u002Fmemories\u002Fpreferences.md`\n- [ ] Did a workflow emerge that could be a new skill? → run `spot-skill-opportunities`\n  to judge whether it's genuinely recurring, then `skill-builder` to create it\n- [ ] Did a heavy skill's fan-out step need a dedicated read-only worker persona\n  (like `dependency-auditor` \u002F `hallucination-detector` \u002F `community-demand-scout`),\n  rather than just a new skill? → run `agent-builder` to scaffold\n  `.claude\u002Fagents\u002F\u003Cname>.md`\n- [ ] Are there existing skills that reference outdated info? → Fix them\n- [ ] Has `learn-staging.md` accumulated entries since the last\n  `promote-memory` run? → fold in a `promote-memory` pass now.\n- [ ] Did I edit one step's scope without updating sibling steps in the same file? →\n  Search the file for all enumerations of the changed category and make them consistent.\n- [ ] Did I add a shared-procedure step to one skill but not to sibling skills? →\n  Grep sibling skills for the same action and add the step there too.\n- [ ] Did I change how a skill describes its relationship\u002Fcontrast to a sibling\n  skill (e.g. \"X is passive, Y is explicit\")? → Grep the sibling skill for its\n  own mirrored description of that same relationship and update it too — a\n  one-directional fix leaves the sibling's docs contradicting the new\n  behavior. (Caught by `@claude` review on ai-config#439: `ums\u002FSKILL.md`'s\n  passive-vs-active contrast with `record-learnings` was fixed, but\n  `record-learnings\u002FSKILL.md`'s own mirrored line describing `ums` as \"the\n  explicit ... counterpart\" was missed until review flagged it as a\n  follow-on.)\n\n## Relationship to record-learnings and staged capture\n\n- `record-learnings` = records individual facts in place, in the moment they arise\n- `ums` = a reflective, full-context sweep — survey what accumulated, categorize it, and persist it all in one committed pass\n\nBoth write to the same destinations. `ums` fires proactively, as soon as a\nlearning worth saving shows up, rather than waiting to catch up later; the\n`\u002Fclear` trigger is only a backstop for anything that slipped through.\n\n`spot-skill-opportunities` is the standing, continuous version of this\nskill's \"did a workflow emerge that could be a new skill?\" checklist item —\nit runs the recognition judgment call live, in the moment, instead of only\nat this checkpoint. `agent-builder` is the sibling construction step for the\nother checklist item above — a recurring fan-out worker persona rather than a\nnew user-invocable skill.\n\n`learn`\u002F`promote-memory` are a staged alternative for the uncertain case:\n`record-learnings` and this skill both write directly to committed memory\nthe moment something looks worth remembering, which is right when you're\nconfident. When you're not — a candidate whose generality or evidence isn't\nsolid yet — `learn` stages it instead, and a `promote-memory` pass (which a\n`ums` run can fold in, or run standalone) reviews staged candidates before\nthey land in committed memory. Neither replaces the direct-write path; they\nadd a review gate for the cases that need one.\n\n## Anti-patterns\n\n- ❌ Saying \"I'll remember that\" without actually writing it down\n- ❌ Updating memories but not pushing skill changes to origin\n- ❌ Recording vague lessons (\"be more careful\") instead of specific ones\n  (\"always poll for new review after pushing --- check commit SHA matches\")\n- ❌ Skipping step 3's dupe check and creating duplicates --\n  specifically, reading only the region you're appending to instead of\n  grepping the corpus for the subject\n- ❌ Updating only preferences when a skill also needs the fix\n- ❌ `git add -A` --- it sweeps unrelated in-flight edits (the user's work, other\n  draft skills) into your commit\u002FPR. Stage the specific files you touched.\n- ❌ Creating `memories\u002Frepo\u002F\u003Crepo>.md` for any repo --- this pattern is retired.\n  Put repo-specific lore in the repo's own agent docs (`.github\u002Fagents\u002F`,\n  `CLAUDE.md`, `.github\u002Finstructions\u002F`, `.github\u002Fcopilot-instructions.md`, or\n  checked-in `.claude\u002Fmemories\u002F`) via a PR;\n  if the repo has no agent-doc infrastructure yet, this session's own local\n  project-memory mechanism (Claude Code: `~\u002F.claude\u002Fprojects\u002F\u003Cproject-path>\u002Fmemory\u002F`\n  --- substitute the equivalent for a non-Claude agent) is short-lived staging\n  only --- hand off that a PR adding those agent docs is still required.\n  See the checklist item above and `memories\u002Fpreferences.md` for the full rule.\n- ❌ Naming a tool, flag, or API identifier that appears **nowhere else in the\n  corpus** without anchoring it somewhere checkable. A lone mention reads\n  identically whether it is correct or hallucinated, so a later session has\n  nothing to verify it against --- and the guidance is only actionable if the\n  name is right. When the identifier is a cross-model tool, add it to\n  `tool-mappings.yml` (then regenerate) rather than leaving the memory bullet\n  as its only home; otherwise cite where you confirmed it. Having *used* it\n  successfully in the session you're writing up is good evidence, but that\n  evidence dies with the session. (ai-config#727: `mcp__github__list_commits`\n  was flagged in review as unanchored; it was genuinely verified by use, and\n  the fix was registering it as the `LIST_COMMITS` operation.)\n- ❌ Writing up an incident from **recall** rather than re-deriving its\n  figures and its mechanism from the artifacts.\n  The artifacts are still there --- that they are still there is exactly why\n  the entry is worth writing now.\n  The bullet above covers an identifier that appears nowhere else;\n  this covers an entry whose identifiers are all real,\n  and whose *quantities* and *causal claim* are invented.\n  It is the harder case, because having **witnessed** the incident feels like\n  evidence,\n  so nothing about composing the entry resembles guessing.\n  Re-read the commit, re-run the command, re-open the issue,\n  and quote what they say ---\n  [`verify-the-right-artifact.md`](..\u002F..\u002Fshared\u002Fworkflow\u002Fverify-the-right-artifact.md)\n  states the general form, that a figure a reader can re-derive beats one you\n  assert.\n  (ai-config#2637: a 37-line entry recording a reformatter incident from\n  earlier the same session drew eight blocking findings from an adversarial\n  self-review --- a count worth attributing, since the PR's own bot review\n  raised one.\n  Nearly every factual claim in the entry was false.\n  \"Three pre-existing paragraphs\" was one,\n  \"200 to 350 characters\" measured 178--268,\n  and \"from 1 to 11\" was 0 to 11.\n  The mechanism was wrong too:\n  the entry blamed `--write` for reflowing whole files,\n  when `--write` has been diff-scoped since #951 and `--all` is what widens\n  it, so the prescribed remedy would not have prevented the churn the entry\n  was written about.\n  The passage was withdrawn rather than patched.\n  The same PR's other half, which survived, carried the matching error in its\n  citations: \"#1373 recorded 47% over\" was 487%, read off that issue's title\n  while its own console block sat below it ---\n  and the passage citing it was citing #2626, whose subject is reading a\n  summary in place of its source.)\n- ❌ Inserting a new bullet into any memory file with nested lists (including\n  `github-actions.md`, `preferences.md`) without checking the surrounding indentation\n  first. These files mix 0-indent top-level bullets with 2-\u002F4-indent sub-bullets and\n  multi-paragraph continuations; a new top-level bullet dropped in the middle\n  of an existing parent's sub-list re-parents whatever follows it in Markdown\n  (a sibling sub-bullet silently becomes this new bullet's child). Before\n  committing an insertion, re-read the few lines immediately above and below\n  the insertion point and confirm the indentation still matches what it did\n  before — or place the new bullet after the complete enclosing list instead\n  of inside it. (Caught by `@claude` review on ai-config#335: a new 0-indent\n  bullet landed between two sibling sub-bullets of an existing parent,\n  breaking the nesting.)\n- ❌ Patching a sentence the entry's point does not need, round after round.\n  When successive review rounds find defects in mechanism prose no reader\n  acts on, delete the prose rather than repair it; the tell is the third\n  round on the same paragraph (ai-config#3193: five successive commits,\n  `1fff7e63` to `4af1f1ea`, each re-patched the same protocol-mechanism\n  sentences, which the entry's Do\u002FDon't never used and `e91dda59` deleted;\n  the deleted paragraphs were not restored).\n  The same shape recurs when a fix round appends prose narrating its own\n  fixes: that prose is fresh unmeasured text, so a round that fixes N\n  findings and adds a paragraph about them adds new claims to refute\n  (ai-config#3202: the three notebook entries narrating rounds 1 to 3 were\n  deleted rather than patched at `48380505`, and the summary entry that\n  replaced them kept being re-edited, its round count rebound to each new\n  head, until the merged file's \"As of `75bc0fc2`, the head round 13\n  reviewed\").\n  Write the fix with no narration;\n  ai-config#3203 proposes the same brief for a fix loop's fixer.\n\n## Proactive hook compliance\n\n- **`remind-ums-after-error.py`**: Prompt-injection hook that fires\n  when an admitted mistake has no subsequent memory or skill modification.\n  Satisfy it by executing `ums` immediately upon acknowledging an error.\n- **`remind-ums-on-scrutiny.py`**: Injects a reminder when a review was read\n  or a questioned claim was corrected without a recorded UMS pass.\n- **`remind-learn-from-review.py`**: Reminds when an accepted reviewer finding\n  has no accompanying learning or guard recorded.\n- **`no-mistake-without-a-hook.py`**: Stop guard and reminder that blocks after an admitted,\n  mechanizable mistake until a hook (`hooks\u002F\u003Cname>.py`), test (`hooks\u002Ftest-\u003Cname>.py`),\n  and manifest binding (`hooks\u002Fhooks.json`) are authored.\n",{"name":5,"description":7,"allowed-tools":24,"user-invocable":29},[25,26,27,28],"Bash","Read","Edit","Write",true,"main","0f720481f8ce3b3d9fef485f6e230d8b3035748e","skills\u002Fums",1,"https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config","https:\u002F\u002Fmorrison-lab.github.io\u002Fai-config\u002F","https:\u002F\u002Fgithub.com\u002FMorrison-Lab","2026-11-15 04:39:15",{"source":8,"skillName":5,"commands":39,"prompt":49,"zipAvailable":29},[40,43,46],{"tool":41,"command":42},"npx","npx skills add Morrison-Lab\u002Fai-config --skill ums",{"tool":44,"command":45},"bunx","bunx skills add Morrison-Lab\u002Fai-config --skill ums",{"tool":47,"command":48},"pnpm","pnpm dlx skills add Morrison-Lab\u002Fai-config --skill ums","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fums\u002FSKILL.md",[],[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M735BVYCGR5VEC65AFDVSNKW","wrap-up","End-of-session verification and UMS.","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fwrap-up\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M735BTH469T1CQ8G2Q9GENCR","workaround-watcher","Watch upstream issue for fix.","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fworkaround-watcher\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M735BRKZWFANSQ0GM380B4TD","wn","→ whats-next.","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fwn\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M735BPE9V830B3B6NGXQ56J6","whats-next","Recommend concrete next step or action.","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fwhats-next\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M735BMHQ60EAD5B7QAWXC5A0","wait-for-results","Wait for pipeline\u002FCI results.","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fwait-for-results\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M735BKGZHPN1PEMJ7YBD5VJ8","wai","→ send-notes.","https:\u002F\u002Fgithub.com\u002FMorrison-Lab\u002Fai-config\u002Fblob\u002Fmain\u002Fskills\u002Fwai\u002FSKILL.md",[],[]]