From ba0a6b391a13048022415098fe82781024e18e06 Mon Sep 17 00:00:00 2001
From: DJJ <shuaiqijianhao@qq.com>
Date: Sun, 24 May 2026 04:34:48 +0800
Subject: [PATCH] Improve llmdoc update workflow

---
 .claude-plugin/marketplace.json               |  4 +-
 .claude-plugin/plugin.json                    |  4 +-
 .codex-plugin/plugin.json                     |  6 +-
 .github/workflows/release.yml                 | 56 ++++++++++++++++
 AGENTS.example.md                             |  4 ++
 CLAUDE.example.md                             |  4 ++
 README.md                                     | 22 +++++--
 README.zh-CN.md                               | 22 +++++--
 agents/investigator.md                        | 17 ++++-
 agents/recorder.md                            | 22 ++++++-
 commands/update.md                            | 66 +++++++++++++++----
 llmdoc/architecture/update-orchestration.md   | 30 +++++++++
 llmdoc/guides/updating-update-workflow.md     | 27 ++++++++
 llmdoc/index.md                               |  3 +
 llmdoc/memory/doc-gaps.md                     |  1 +
 llmdoc/must/doc-routing.md                    |  1 +
 llmdoc/must/working-agreement.md              |  2 +
 llmdoc/reference/repo-surfaces.md             |  3 +-
 skills/README.md                              |  2 +
 skills/llmdoc-update/SKILL.md                 | 41 ++++++++----
 skills/llmdoc/SKILL.md                        |  1 +
 skills/llmdoc/references/codex-cli-hooks.md   |  5 +-
 skills/llmdoc/references/doc-structure.md     | 23 ++++++-
 skills/llmdoc/references/templates.md         |  9 +++
 skills/llmdoc/references/update-and-memory.md | 47 +++++++++++--
 skills/llmdoc/templates/stop.sh               |  2 +-
 26 files changed, 368 insertions(+), 56 deletions(-)
 create mode 100644 .github/workflows/release.yml
 create mode 100644 llmdoc/architecture/update-orchestration.md
 create mode 100644 llmdoc/guides/updating-update-workflow.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 63cdc5c..b5c568b 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -4,12 +4,12 @@
     "name": "TokenRoll",
     "email": "shuaiqijianaho@qq.com"
   },
-  "description": "Marketplace for the minimal llmdoc Claude Code workflow",
+  "description": "Marketplace for the llmdoc Claude Code workflow",
   "plugins": [
     {
       "name": "llmdoc",
       "source": "./",
-      "description": "Minimal llmdoc workflow for Claude Code: init, update, and use"
+      "description": "llmdoc workflow for Claude Code: init, update modes, temporary investigation cache, and use"
     }
   ]
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 6ffecce..8f13ded 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "description": "llmdoc Claude Code plugin with a minimal workflow: init, update, and use",
-  "version": "2.0.0",
+  "description": "llmdoc Claude Code plugin with init, update modes, temporary investigation cache, and use",
+  "version": "2.1.0",
   "author": {
     "name": "DJJ & Danniel"
   }
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index e1445b3..61dc1f5 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "version": "2.0.0",
-  "description": "Doc-driven workflow with startup docs, reflections, update prompts, and reusable skills for Codex.",
+  "version": "2.1.0",
+  "description": "Doc-driven workflow with startup docs, update modes, temporary investigation cache, and reusable skills for Codex.",
   "author": {
     "name": "DJJ & Danniel",
     "email": "shuaiqijianaho@qq.com",
@@ -13,7 +13,7 @@
   "interface": {
     "displayName": "llmdoc",
     "shortDescription": "Doc-driven coding workflow",
-    "longDescription": "Use startup docs, guides, reflections, and update prompts to improve coding quality and reduce repeated mistakes.",
+    "longDescription": "Use startup docs, guides, update modes, temporary investigation cache, and focused reflections to improve coding quality and reduce repeated work.",
     "developerName": "TokenRoll",
     "category": "Productivity",
     "capabilities": ["Read", "Write"],
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..c81e095
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Publish GitHub Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Build release notes
+        id: notes
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          tag="${GITHUB_REF_NAME}"
+          previous_tag="$(git tag --sort=-creatordate | grep -v "^${tag}$" | head -n 1 || true)"
+
+          {
+            echo "## Changes"
+            echo
+            if [ -n "$previous_tag" ]; then
+              git log --pretty='- %s (%h)' "${previous_tag}..${tag}"
+            else
+              git log --pretty='- %s (%h)' "${tag}"
+            fi
+            echo
+            echo "## Changed Files"
+            echo
+            if [ -n "$previous_tag" ]; then
+              git diff --name-only "${previous_tag}..${tag}" | sed 's/^/- /'
+            else
+              git show --name-only --pretty='' "${tag}" | sed '/^$/d; s/^/- /'
+            fi
+          } > release-notes.md
+
+      - name: Publish release
+        uses: softprops/action-gh-release@6cbd405e2c4e67a21c47fa9e383d020e4e28b836 # v2.3.3
+        with:
+          body_path: release-notes.md
diff --git a/AGENTS.example.md b/AGENTS.example.md
index 56c6236..a159706 100644
--- a/AGENTS.example.md
+++ b/AGENTS.example.md
@@ -4,6 +4,10 @@ Before broad source-code exploration, planning, or documentation work, load the
 
 The main assistant should align with the user before non-trivial plans or edits.
 
+Use available `llmdoc` subagents when they fit the task. Prefer `investigator` for context exploration, current-state research, unfamiliar subsystems, and reusable scratch reports; use `recorder` for stable doc updates, `worker` for scoped implementation, and `reflector` for process lessons.
+
 At the end of a non-trivial task, when the work produced durable knowledge, workflow lessons, or useful reflections, the main assistant should proactively use the `llmdoc-update` skill in Codex.
 
+Treat `.llmdoc-tmp/` as a local temporary context cache only. Validate scratch reports before reuse; tracked `llmdoc/` docs are the project knowledge source.
+
 Keep detailed workflow rules, templates, hook behavior, and doc-structure guidance in the `llmdoc` skill.
diff --git a/CLAUDE.example.md b/CLAUDE.example.md
index a5c105e..2b3c489 100644
--- a/CLAUDE.example.md
+++ b/CLAUDE.example.md
@@ -5,7 +5,11 @@ Load the `llmdoc` skill before broad code exploration, planning, document update
 
 The main assistant should align with the user before non-trivial plans or edits.
 
+Use available `llmdoc` subagents when they fit the task. Prefer `investigator` for context exploration, current-state research, unfamiliar subsystems, and reusable scratch reports; use `recorder` for stable doc updates, `worker` for scoped implementation, and `reflector` for process lessons.
+
 At the end of a non-trivial task, the main assistant should evaluate whether to ask the user to run `/llmdoc:update`.
 
+Treat `.llmdoc-tmp/` as a local temporary context cache only. Validate scratch reports before reuse; tracked `llmdoc/` docs are the project knowledge source.
+
 Keep detailed workflow rules, templates, hook behavior, and doc-structure guidance in the `llmdoc` skill.
 <system-reminder>
diff --git a/README.md b/README.md
index 5060b6b..7bbe6cc 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ The default setup is simple:
 - the core skill entry is short, while detailed rationale, protocols, and templates are split under `skills/llmdoc/references/`
 - the core skill defines proactive guide/reflection reading and proactive user discussion before non-trivial edits
 - the workflow restores the good pattern of proactively asking whether to run `/llmdoc:update` at the end of non-trivial tasks
+- `/llmdoc:update` supports lightweight and heavier modes, so immediate post-task doc updates do not always require a full multi-agent pipeline
 - helper Codex skills provide command-like entrypoints without pretending Codex has custom slash commands for this plugin
 - agents and command contracts stay focused on execution instead of carrying a large amount of duplicated guidance
 
@@ -65,14 +66,23 @@ Use `/llmdoc:update` after meaningful work when project knowledge should be pers
 In Claude Code, this is a command.
 In Codex, use the helper skill `llmdoc-update` for the equivalent workflow.
 
+The command keeps tracked `llmdoc/` docs consistent with the current repository. Stable docs should stay compact: either smaller than the source they describe or useful because they explain architecture, implementation intent, boundaries, and stable contracts.
+
+The command selects the lightest mode that can keep docs correct:
+
+- `fast`: default for immediate post-implementation updates when the coordinating assistant has fresh context
+- `analysis`: one focused evidence pass for stale context, current-state research, or unclear impact
+- `full`: separate investigation, reflection, and recording when risk or process learning justifies the extra independence
+
 The command:
 
 1. Rebuilds context from llmdoc and the current working tree
 2. Proactively reads relevant guides and reflections
-3. Investigates impacted concepts
-4. Writes a reflection under `llmdoc/memory/reflections/`
-5. Updates stable docs
-6. Synchronizes `llmdoc/index.md`
+3. Chooses an update mode
+4. Investigates impacted concepts only when the selected mode requires it
+5. Writes a reflection under `llmdoc/memory/reflections/` only when there is a workflow lesson or missing-doc signal
+6. Updates stable docs and reconciles `llmdoc/memory/doc-gaps.md`
+7. Synchronizes `llmdoc/index.md`
 
 In normal use, the main assistant should proactively ask whether to run `/llmdoc:update` when the task produced durable knowledge or a useful reflection.
 
@@ -100,11 +110,13 @@ llmdoc/
 `llmdoc/startup.md` is only the startup reading order.
 They should link to each other, but they should not repeat the same content.
 
+`.llmdoc-tmp/` is a local temporary context cache. Investigator reports can persist across nearby sessions and help avoid repeated research, but they are ignored by git, not indexed, and not a source of truth. Promote only durable conclusions into tracked `llmdoc/` docs.
+
 ## Internal Agents
 
 | Agent | Purpose |
 |------|---------|
-| `investigator` | Evidence gathering for chat or temporary scratch reports |
+| `investigator` | Evidence gathering for chat, current-state research, or temporary scratch reports |
 | `worker` | Executes well-defined tasks |
 | `recorder` | Maintains stable llmdoc documents |
 | `reflector` | Writes post-task reflections |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 2408dad..99b4bcc 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -12,6 +12,7 @@
 - core skill 入口保持简短，详细的方法论、协议和模板拆到 `skills/llmdoc/references/`
 - core skill 还定义了主动阅读 guides/reflection，以及在非简单改动前主动和用户沟通
 - 整套工作流还恢复了一个好模式：在非简单任务结束时，主动询问是否运行 `/llmdoc:update`
+- `/llmdoc:update` 支持轻量和重型模式，所以刚完成实现后的文档更新不必每次都跑完整多 agent 流水线
 - Codex helper skills 提供了接近 command 的入口，但不会误导用户以为 Codex 已经支持这个插件的自定义 slash command
 - agent 和 command contract 只负责执行，不再各自复制一大段说明
 
@@ -65,14 +66,23 @@
 在 Claude Code 里，它是 command。
 在 Codex 里，用 helper skill `llmdoc-update` 走等价工作流。
 
+这个命令会让 tracked `llmdoc/` 文档和当前仓库保持一致。稳定文档应该保持紧凑：要么比它描述的源码更小，要么能解释源码搜索无法快速提供的架构、实现意图、边界和稳定契约。
+
+这个命令会选择能保证文档正确的最轻模式：
+
+- `fast`：默认模式，适合主 assistant 刚完成实现、上下文仍然新鲜的情况
+- `analysis`：适合上下文变旧、需要调研当前现状、或影响范围不清时的一次聚焦证据 pass
+- `full`：适合风险较高、事实有争议、或确实需要独立反思与复核的情况
+
 这个命令会：
 
 1. 基于 llmdoc 和当前 working tree 重建上下文
 2. 主动阅读相关 guides 和 reflection
-3. 调研受影响的概念
-4. 在 `llmdoc/memory/reflections/` 下写 reflection
-5. 更新稳定文档
-6. 同步 `llmdoc/index.md`
+3. 选择 update mode
+4. 只在所选模式需要时调研受影响的概念
+5. 只有出现工作流教训或缺失文档信号时，才在 `llmdoc/memory/reflections/` 下写 reflection
+6. 更新稳定文档，并清账 `llmdoc/memory/doc-gaps.md`
+7. 同步 `llmdoc/index.md`
 
 在日常使用里，如果任务产生了值得长期保留的知识或反思，主 assistant 应该主动询问是否现在运行 `/llmdoc:update`。
 
@@ -100,11 +110,13 @@ llmdoc/
 `llmdoc/startup.md` 只负责启动阅读顺序。
 两者可以互相链接，但不应该重复同一批内容。
 
+`.llmdoc-tmp/` 是本地临时 context cache。investigator 报告可以跨相邻会话保留，帮助减少重复调研，但它被 git 忽略、不会进入 index，也不是 source of truth。只有稳定、可复用的结论才应该提升到 tracked `llmdoc/` 文档里。
+
 ## 内部 Agents
 
 | Agent | 用途 |
 |------|------|
-| `investigator` | 做证据驱动的调研，可回对话，也可输出临时调查草稿 |
+| `investigator` | 做证据驱动的调研，可回对话、调研当前现状，也可输出临时调查草稿 |
 | `worker` | 执行明确的任务 |
 | `recorder` | 维护稳定 llmdoc 文档 |
 | `reflector` | 记录任务后的 reflection |
diff --git a/agents/investigator.md b/agents/investigator.md
index 64d533e..b5f108a 100644
--- a/agents/investigator.md
+++ b/agents/investigator.md
@@ -1,6 +1,6 @@
 ---
 name: investigator
-description: "Evidence-driven codebase investigation for init, update, and ad-hoc analysis. Supports chat replies and temporary scratch reports."
+description: "Evidence-driven codebase investigation for init, update, current-state research, and ad-hoc analysis. Supports chat replies and temporary scratch reports."
 tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, Write, Edit
 model: opus
 color: cyan
@@ -8,6 +8,8 @@ color: cyan
 
 You are `investigator`, an evidence-first agent used to understand the codebase and produce a reusable retrieval map for other agents.
 
+Investigator output can support init, update, or current-state research. It is not stable project memory by itself.
+
 When invoked:
 
 1. Read `llmdoc/index.md` when it exists.
@@ -16,7 +18,7 @@ When invoked:
 4. Read the remaining task-relevant documents from `overview/`, `architecture/`, and `reference/`.
 5. Investigate source code to fill gaps left by the docs.
 6. If you enter a new subsystem, find conflicting evidence, or hit an execution failure, re-read relevant guides and reflections before expanding code search.
-7. Produce the requested output either directly in conversation or as a persistent file.
+7. Produce the requested output either directly in conversation or as a temporary scratch file.
 
 Key practices:
 
@@ -25,6 +27,8 @@ Key practices:
 - **Use line numbers sparingly:** Add line numbers only when they are required to prove a disputed or non-obvious behavior.
 - **Objective:** Report facts and evidence, not design opinions.
 - **Split by sink:** `sink=chat` is for direct answers. `sink=file` is for temporary scratch artifacts, usually under `.llmdoc-tmp/investigations/`.
+- **Temporary means temporary:** `.llmdoc-tmp/` may persist across sessions, but it is ignored by git, not indexed by `llmdoc/index.md`, and can be deleted at any time.
+- **Make reuse safe:** File reports should record date, git revision when available, evidence scope, unresolved gaps, and whether the report is safe to reuse.
 - **No long code pastes:** The reader can open source files directly.
 
 <InputFormat>
@@ -65,7 +69,14 @@ Key practices:
   </OutputFormat_Chat>
 
 <OutputFormat_File>
-Write a markdown file using the same section layout as `<OutputFormat_Chat>`, then return the absolute file path.
+Write a markdown file using the same section layout as `<OutputFormat_Chat>`, plus this metadata block near the top:
+
+- Date:
+- Git Revision:
+- Evidence Scope:
+- Reuse Conditions:
+
+Then return the absolute file path.
 </OutputFormat_File>
 
 Always ensure the investigation is specific, factual, and easy for another agent to reuse.
diff --git a/agents/recorder.md b/agents/recorder.md
index abfaf8e..5cba813 100644
--- a/agents/recorder.md
+++ b/agents/recorder.md
@@ -8,19 +8,29 @@ color: green
 
 You are `recorder`, the agent responsible for stable llmdoc maintenance.
 
-Your job is to update durable documentation, not to dump raw notes. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`. Reflections belong to `reflector`. You also own `memory/decisions/` and `memory/doc-gaps.md`.
+Your job is to keep tracked `llmdoc/` docs consistent with the current repository, not to dump raw notes. Stable docs should be smaller than the source they describe or add architectural explanation, implementation intent, boundaries, and retrieval value. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`. Reflections belong to `reflector`. You also own `memory/decisions/` and `memory/doc-gaps.md`.
 
 When invoked:
 
 1. Read `llmdoc/index.md` and `llmdoc/startup.md` when they exist.
 2. Proactively read relevant guides and reflections before deciding how stable docs should change.
-3. Read the relevant raw investigation reports when the task depends on temporary scratch findings, especially during `/llmdoc:init`.
+3. Read the relevant raw investigation reports when the task depends on temporary scratch findings, especially during `/llmdoc:init` or `/llmdoc:update mode=analysis`.
+   - Validate scratch report date, git revision, evidence scope, and unresolved gaps before reusing it.
+   - Treat scratch as evidence, not as source of truth.
 4. Determine the impacted concepts and map each one to the correct llmdoc category.
 5. Keep `llmdoc/index.md` and `llmdoc/startup.md` distinct in purpose and content.
 6. During `/llmdoc:init`, prefer a small number of deep core docs before expanding into many narrower docs.
 7. Update the touched documents and synchronize `llmdoc/index.md`.
 8. Report every file you created, updated, or deleted.
 
+Consistency rules:
+
+- Correct or remove stable-doc claims that no longer match the current code.
+- Do not preserve stale facts just because they were previously documented.
+- Do not add volatile counts, line totals, or incidental implementation inventory unless they are part of a stable contract.
+- Do not index `.llmdoc-tmp/`.
+- Reconcile `memory/doc-gaps.md` during non-trivial updates: close resolved gaps, mark stale gaps, and add only actionable gaps with closure criteria.
+
 llmdoc categories:
 
 - `/must/`: Tiny startup documents that should be read on every run. Only recurring, cross-task, stable knowledge belongs here.
@@ -30,6 +40,14 @@ llmdoc categories:
 - `/reference/`: Stable lookup facts, contracts, schemas, conventions.
 - `/memory/`: Historical process memory such as reflections, decisions, and doc gaps. `reflector` owns `memory/reflections/`. `recorder` owns `memory/decisions/` and `memory/doc-gaps.md`.
 
+Routing tests:
+
+- Use `/must/` only for short, recurring rules that are likely to prevent mistakes on most tasks.
+- Use `/architecture/` for flows, ownership boundaries, invariants, and why the implementation is shaped that way.
+- Use `/reference/` for stable lookup facts and contracts.
+- Use `/guides/` for repeatable workflows.
+- Leave raw investigation, volatile observations, and one-off evidence in `.llmdoc-tmp/`.
+
 Index rules:
 
 - `llmdoc/index.md` is the global map of the documentation system.
diff --git a/commands/update.md b/commands/update.md
index 7244be7..efe31b1 100644
--- a/commands/update.md
+++ b/commands/update.md
@@ -1,20 +1,41 @@
 ---
-description: "Persist newly learned project knowledge by reflecting first and then updating llmdoc."
+description: "Keep tracked llmdoc docs current with the repository using the lightest sufficient update mode."
 argument-hint: "[optional summary of what changed]"
 ---
 
 # /llmdoc:update
 
-Use this command after a task when the project knowledge, workflow guidance, or doc structure should be updated.
+Use this command after a task when the tracked project knowledge, workflow guidance, or doc structure should be updated.
+
+The goal is not to archive everything the task discovered. The goal is to keep tracked `llmdoc/` docs consistent with the current repository while staying smaller than the source code or adding architectural explanation the source cannot provide by itself.
 
 Before executing the workflow, load the `llmdoc` skill.
 
 Why:
 
 - the skill defines what belongs in `must/`, stable docs, and memory
-- the skill explains why reflection happens before stable doc updates
+- the skill explains update modes, memory handling, and when reflection is useful
 - this command should focus on orchestration, not re-explain the whole system
 
+## Mode Selection
+
+Choose the lightest mode that can keep the docs correct.
+
+- `fast` is the default when the coordinating assistant just implemented the change and has fresh context. Skip mandatory investigation and update stable docs from the task summary, diff, targeted checks, and any still-valid local scratch reports.
+- `analysis` is for stale context, unclear impact, current-state research, or handoff work. Use one focused analysis pass, usually `investigator` with `sink=file`, then let `recorder` consume the scratch report and the current working tree.
+- `full` is for high-risk rewrites, init-like rebootstrap work, disputed facts, or reflection-heavy failures. Use investigator, reflector, and recorder as separate roles.
+
+Escalate from `fast` to `analysis` when the assistant cannot name the impacted docs confidently. Escalate to `full` when independent review is more valuable than speed.
+
+## `.llmdoc-tmp/`
+
+`.llmdoc-tmp/` is a local temporary context cache, not stable project memory.
+
+- Investigator reports may be retained across sessions under `.llmdoc-tmp/investigations/`.
+- They are ignored by git, not indexed by `llmdoc/index.md`, and may be deleted at any time.
+- Reuse them only after checking their recorded git revision, scope, and unresolved gaps against the current repository.
+- Promote only durable conclusions into tracked `llmdoc/` docs.
+
 ## Actions
 
 1. Rebuild task context.
@@ -22,23 +43,40 @@ Why:
    - Read `llmdoc/startup.md` and the files it lists when available.
    - Proactively read relevant `llmdoc/guides/` and `llmdoc/memory/reflections/` before planning edits.
    - Inspect the current working tree, staged changes, and any explicit change summary from `$ARGUMENTS`.
+   - Check whether relevant `.llmdoc-tmp/investigations/` reports exist, but treat them as temporary evidence to validate, not as truth.
 
-2. Investigate the impacted concepts.
-   - Use `investigator`.
-   - Prefer targeted questions over broad repo scans.
-   - Persist temporary investigation notes under `.llmdoc-tmp/investigations/` only when they help the current update.
+2. Select the update mode.
+   - Prefer `fast` for immediate post-implementation updates by the same assistant.
+   - Use `analysis` when the current state needs a fresh evidence map.
+   - Use `full` when the update needs independent reflection or risk review.
 
-3. Reflect before editing stable docs.
-   - Use `reflector` to write a task-specific reflection into `llmdoc/memory/reflections/`.
-   - Capture mistakes, missing docs, bad assumptions, and promotion candidates.
+3. Investigate only when the selected mode needs it.
+   - In `fast`, prefer targeted checks and the coordinating assistant's fresh task summary.
+   - In `analysis`, use `investigator` for a single focused scratch report under `.llmdoc-tmp/investigations/`.
+   - In `full`, use separate investigation and reflection steps.
+   - Prefer targeted questions over broad repo scans in every mode.
 
-4. Update stable llmdoc with `recorder`.
+4. Reflect only when reflection has value.
+   - In `full`, use `reflector` to write the reflection so independent role review is preserved.
+   - In `fast` or `analysis`, write a task-specific reflection into `llmdoc/memory/reflections/` only when the task exposed a workflow failure, repeated mistake, missing signal, or durable process lesson.
+   - Do not force a reflection for routine `fast` updates that only keep stable docs current.
+
+5. Update stable llmdoc with `recorder`.
    - Update only the impacted docs.
-   - Promote lessons into `must/`, `guides/`, or `reference/` only when they are stable and likely to recur.
+   - Remove or correct stable-doc claims that no longer match the current code.
+   - Promote lessons into `must/`, `guides/`, `architecture/`, or `reference/` only when they are stable and likely to recur.
    - Split documents aggressively instead of appending to a large file.
+   - Keep tracked docs compact: they should be smaller than the source they describe or explain design and implementation intent that source search does not expose quickly.
+   - Reconcile `llmdoc/memory/doc-gaps.md`: close resolved gaps, mark stale gaps, and add only actionable new gaps with closure criteria.
+
+6. Run the active-memory archive check.
+   - After any new reflection is written, count active memory files under `llmdoc/memory/`, excluding `llmdoc/memory/lessons-learned.md`, `llmdoc/memory/doc-gaps.md`, and anything under `llmdoc/memory/archive/`.
+   - If the count is greater than 5, follow `skills/llmdoc/references/lessons-learned.md`: summarize recurring lessons into `llmdoc/memory/lessons-learned.md`, link each lesson to its source memory file, and move summarized raw memory into `llmdoc/memory/archive/YYYY-MM-DD/`.
+   - Treat hook reminders as best-effort only; this workflow step is the precise archive checkpoint.
 
-5. Synchronize `llmdoc/index.md`.
+7. Synchronize `llmdoc/index.md`.
    - Ensure new and changed docs are discoverable.
    - Keep reflections and decisions listed separately from stable docs.
+   - Do not index `.llmdoc-tmp/`.
 
-6. Report the reflection path and the stable docs that changed.
+8. Report the mode used, any scratch report or reflection path, the archive action taken or skipped, and the stable docs that changed.
diff --git a/llmdoc/architecture/update-orchestration.md b/llmdoc/architecture/update-orchestration.md
new file mode 100644
index 0000000..914284e
--- /dev/null
+++ b/llmdoc/architecture/update-orchestration.md
@@ -0,0 +1,30 @@
+# Update Orchestration
+
+## Purpose
+- Define how `/llmdoc:update` keeps tracked `llmdoc/` docs aligned with the current repository without forcing unnecessary multi-agent work.
+- Preserve independent investigation when it is useful, while making immediate post-implementation updates fast.
+
+## Knowledge Layers
+- `llmdoc/`: tracked project knowledge. It should describe current architecture, implementation intent, boundaries, stable contracts, and recurring workflow rules.
+- `.llmdoc-tmp/`: local temporary context cache. It may hold investigator reports or hook logs, but it is ignored by git, not indexed, and may be deleted.
+- Source code and git state: the final authority for volatile facts, counts, and implementation details.
+
+## Update Modes
+- `fast`: default for immediate post-task updates by the same coordinating assistant. Use the task summary, diff, targeted checks, and any still-valid scratch reports.
+- `analysis`: use when the current state needs fresh evidence, the implementation context is stale, or the impacted docs are unclear. Run one focused investigation and persist the scratch report under `.llmdoc-tmp/investigations/`.
+- `full`: use when risk, disputed facts, or process learning justify separate investigator, reflector, and recorder roles.
+
+## Invariants
+- Stable docs must not describe behavior that no longer exists in the current repository.
+- Stable docs should be smaller than the source they describe or add architectural explanation that source search does not provide quickly.
+- Investigator reports are reusable evidence, not stable memory or source of truth.
+- Reflections are written only when there is a workflow failure, repeated mistake, missing signal, or durable process lesson.
+- `recorder` reconciles `llmdoc/memory/doc-gaps.md` during non-trivial updates.
+- `llmdoc/index.md` never indexes `.llmdoc-tmp/`.
+
+## Routing
+- Use `must/` for short recurring rules that prevent common mistakes.
+- Use `architecture/` for flows, ownership boundaries, invariants, and design intent.
+- Use `reference/` for stable lookup facts and contracts.
+- Use `guides/` for repeatable workflows.
+- Leave raw evidence, volatile observations, and current-state scratch notes in `.llmdoc-tmp/`.
diff --git a/llmdoc/guides/updating-update-workflow.md b/llmdoc/guides/updating-update-workflow.md
new file mode 100644
index 0000000..7b229d9
--- /dev/null
+++ b/llmdoc/guides/updating-update-workflow.md
@@ -0,0 +1,27 @@
+# How to Update the Update Workflow
+
+## Preconditions
+- Read `llmdoc/architecture/update-orchestration.md`.
+- Inspect both Claude Code command docs and Codex helper skills before changing behavior.
+
+## Main Steps
+1. Update `commands/update.md` when the Claude Code command contract changes.
+2. Update `skills/llmdoc-update/SKILL.md` so Codex follows the same contract.
+3. Update `agents/investigator.md` if scratch report behavior, metadata, or reuse rules change.
+4. Update `agents/recorder.md` if stable-doc consistency, doc-gaps reconciliation, or routing rules change.
+5. Update `.codex/agents/*.toml` when project-scoped Codex subagent behavior changes.
+6. Update `README.md` and `README.zh-CN.md` so the public workflow summary matches the actual contract.
+7. Update plugin manifest versions together for Claude Code and Codex when publishing a behavior change.
+
+## Verification
+- `/llmdoc:update` describes `fast`, `analysis`, and `full` modes.
+- Codex `llmdoc-update` describes the same modes.
+- Investigator reports are described as temporary context cache, not stable docs.
+- Recorder rules require stable docs to match current code and reconcile `doc-gaps.md`.
+- Public README summaries match both Claude Code and Codex behavior.
+
+## Common Failure Points
+- Changing only the Claude Code command while leaving Codex helper skills stale.
+- Treating `.llmdoc-tmp/` as durable project memory because reports persist locally.
+- Requiring reflection for routine updates with no process lesson.
+- Adding volatile counts or raw inventory to stable docs instead of checking them on demand.
diff --git a/llmdoc/index.md b/llmdoc/index.md
index 7214f8c..04d4fc4 100644
--- a/llmdoc/index.md
+++ b/llmdoc/index.md
@@ -16,13 +16,16 @@
 - `llmdoc/startup.md`: ordered startup reading list
 - `llmdoc/overview/project-overview.md`: what this repository is and what belongs here
 - `llmdoc/architecture/init-investigation-orchestration.md`: how `/llmdoc:init` investigation is expected to fan out and converge
+- `llmdoc/architecture/update-orchestration.md`: how `/llmdoc:update` chooses fast, analysis, or full update paths
 - `llmdoc/guides/updating-init-investigation-depth.md`: how to change init depth safely when the workflow is too shallow or too broad
+- `llmdoc/guides/updating-update-workflow.md`: how to update the update workflow across Claude Code, Codex, agents, and docs
 - `llmdoc/reference/repo-surfaces.md`: stable map of commands, agents, plugin files, and Codex config surfaces
 
 ## Routing Rules
 - Read `startup.md` first on normal work.
 - Read `architecture/init-investigation-orchestration.md` before changing `/llmdoc:init`, agent fan-out strategy, or Codex agent limits.
 - Read `guides/updating-init-investigation-depth.md` before tuning investigation breadth or follow-up passes.
+- Read `architecture/update-orchestration.md` and `guides/updating-update-workflow.md` before changing `/llmdoc:update`, `llmdoc-update`, investigator scratch behavior, or recorder update rules.
 - Read `reference/repo-surfaces.md` before moving or renaming public repo surfaces such as commands, agents, plugin files, or `.codex/config.toml`.
 
 ## Memory
diff --git a/llmdoc/memory/doc-gaps.md b/llmdoc/memory/doc-gaps.md
index 3a25293..7075d91 100644
--- a/llmdoc/memory/doc-gaps.md
+++ b/llmdoc/memory/doc-gaps.md
@@ -3,3 +3,4 @@
 ## Open Gaps
 - There is still no executable test or fixture that validates `/llmdoc:init` fan-out behavior against the documented contract; current confidence comes from prompt and config review.
 - If runtime behavior diverges again, add a guide or fixture that checks command docs, README summaries, and `.codex/config.toml` together.
+- `.codex/agents/llmdoc-investigator.toml` and `.codex/agents/llmdoc-recorder.toml` still need to mirror the new update-mode and temporary-cache rules once the hidden `.codex/` directory is writable in the working environment.
diff --git a/llmdoc/must/doc-routing.md b/llmdoc/must/doc-routing.md
index f709f62..71bb92e 100644
--- a/llmdoc/must/doc-routing.md
+++ b/llmdoc/must/doc-routing.md
@@ -2,6 +2,7 @@
 
 ## Read Next By Task
 - For `/llmdoc:init` changes: read `llmdoc/architecture/init-investigation-orchestration.md` and `llmdoc/guides/updating-init-investigation-depth.md`.
+- For `/llmdoc:update` changes: read `llmdoc/architecture/update-orchestration.md` and `llmdoc/guides/updating-update-workflow.md`.
 - For public interface or repo layout changes: read `llmdoc/overview/project-overview.md` and `llmdoc/reference/repo-surfaces.md`.
 - For repeated workflow mistakes or regressions: read the relevant files under `llmdoc/memory/reflections/` first.
 
diff --git a/llmdoc/must/working-agreement.md b/llmdoc/must/working-agreement.md
index f9d011e..3cad856 100644
--- a/llmdoc/must/working-agreement.md
+++ b/llmdoc/must/working-agreement.md
@@ -5,9 +5,11 @@
 - Prefer docs first, code and config second.
 - The main assistant aligns with the user before non-trivial edits.
 - Temporary investigation artifacts belong in `.llmdoc-tmp/`, not stable llmdoc docs.
+- `.llmdoc-tmp/` is only a local temporary context cache; validate scratch reports before reuse and never treat them as source of truth.
 - Use `/llmdoc:update` when a task changes workflow knowledge, architecture understanding, or recurring conventions.
 
 ## Editing Bias
 - Keep startup docs small.
 - Split stable docs by concept instead of appending large mixed documents.
 - Promote only durable lessons into `must/`, `guides/`, `architecture/`, or `reference/`.
+- Keep stable docs consistent with the current code while avoiding volatile counts or raw implementation inventory.
diff --git a/llmdoc/reference/repo-surfaces.md b/llmdoc/reference/repo-surfaces.md
index 764dbd9..f66958d 100644
--- a/llmdoc/reference/repo-surfaces.md
+++ b/llmdoc/reference/repo-surfaces.md
@@ -5,7 +5,7 @@
 
 ## Stable Facts
 - `commands/init.md`: Contract for initializing or re-bootstrapping llmdoc.
-- `commands/update.md`: Contract for reflecting first and then updating stable docs.
+- `commands/update.md`: Contract for selecting an update mode and keeping tracked stable docs current.
 - `skills/llmdoc/SKILL.md`: Core operating skill for llmdoc projects.
 - `skills/llmdoc-init/SKILL.md` and `skills/llmdoc-update/SKILL.md`: Codex-native helper entry skills that mirror `/llmdoc:init` and `/llmdoc:update`.
 - `agents/investigator.md`, `agents/worker.md`, `agents/recorder.md`, `agents/reflector.md`: Claude-style role prompts for the internal workflow.
@@ -19,4 +19,5 @@
 - `README.zh-CN.md` (`公开接口`): Chinese user-facing contract.
 - `commands/init.md` (`/llmdoc:init`): Init workflow source of truth.
 - `commands/update.md` (`/llmdoc:update`): Update workflow source of truth.
+- `llmdoc/architecture/update-orchestration.md` (`/llmdoc:update` design): Update mode and knowledge-layer source of truth.
 - `.codex/config.toml` (`[agents]`): Codex runtime limit source of truth.
diff --git a/skills/README.md b/skills/README.md
index 30950e8..4f4a142 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -12,3 +12,5 @@ Recommended setup:
 - Keep the detailed working model in `skills/llmdoc/references/`
 - Keep reusable Codex hook and script templates in `skills/llmdoc/templates/`
 - Let the skill carry the proactive guide/reflection reading protocol and the proactive user-discussion protocol
+- Keep `/llmdoc:update` behavior aligned across Claude Code commands, Codex helper skills, public README files, and project-scoped agents
+- Treat `.llmdoc-tmp/` as a local temporary context cache, not stable project memory
diff --git a/skills/llmdoc-update/SKILL.md b/skills/llmdoc-update/SKILL.md
index 6a4eaa7..0b6050a 100644
--- a/skills/llmdoc-update/SKILL.md
+++ b/skills/llmdoc-update/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: llmdoc-update
-description: "Codex-native entry skill for reflecting first and then updating llmdoc. Use this when you want the /llmdoc:update workflow in Codex."
+description: "Codex-native entry skill for keeping tracked llmdoc docs current with the repository. Use this when you want the /llmdoc:update workflow in Codex."
 disable-model-invocation: false
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit, WebSearch, WebFetch
 ---
@@ -9,6 +9,8 @@ allowed-tools: Read, Glob, Grep, Bash, Write, Edit, WebSearch, WebFetch
 
 This skill is the Codex-native equivalent of `/llmdoc:update`.
 
+The update target is tracked `llmdoc/`, not `.llmdoc-tmp/`. Stable docs should stay consistent with the current repository and remain smaller than the source code or provide architectural explanation that source search does not.
+
 Use it when:
 
 - a task changed project knowledge, architecture understanding, or workflow guidance
@@ -20,6 +22,8 @@ Before editing stable docs:
 - read `llmdoc/index.md`
 - read `llmdoc/startup.md` and the MUST docs it lists
 - proactively read relevant `llmdoc/guides/` and `llmdoc/memory/reflections/`
+- read `skills/llmdoc/references/lessons-learned.md` for the active-memory archive threshold and archive procedure
+- check relevant `.llmdoc-tmp/investigations/` reports only as local temporary evidence, validating their git revision, scope, and gaps before reuse
 - align with the user before non-trivial edits
 
 Then execute this workflow:
@@ -28,23 +32,38 @@ Then execute this workflow:
    - Inspect the current working tree, staged changes, and any explicit task summary.
    - Prefer targeted investigation over broad repo scans.
 
-2. Investigate the impacted concepts.
-   - Use short, evidence-first exploration.
-   - Persist temporary investigation notes under `.llmdoc-tmp/investigations/` only when they help the current update.
+2. Select the lightest update mode that keeps docs correct.
+   - `fast`: default for immediate post-implementation updates when the coordinating assistant has fresh context. Use the task summary, diff, targeted checks, and any still-valid scratch reports.
+   - `analysis`: use when current-state research, stale context, or unclear impact requires one focused evidence pass. Persist the report under `.llmdoc-tmp/investigations/`.
+   - `full`: use when risk, disputed facts, or process learning justify separate investigation, reflection, and recording roles.
+
+3. Investigate only as needed by the selected mode.
+   - In `fast`, do targeted checks instead of mandatory broad investigation.
+   - In `analysis`, write one focused scratch report under `.llmdoc-tmp/investigations/`.
+   - In `full`, keep investigation and reflection as separate steps.
 
-3. Reflect before editing stable docs.
-   - Write a task-specific reflection under `llmdoc/memory/reflections/`.
-   - Capture mistakes, missing docs, bad assumptions, and promotion candidates.
+4. Reflect only when reflection has value.
+   - In `full`, use `reflector` to write the reflection so independent role review is preserved.
+   - In `fast` or `analysis`, write a task-specific reflection under `llmdoc/memory/reflections/` only when there was a workflow failure, repeated mistake, missing signal, or durable process lesson.
+   - Do not force a reflection for routine `fast` updates.
 
-4. Update stable llmdoc docs.
+5. Update stable llmdoc docs.
    - Update only the impacted docs.
-   - Promote lessons into `must/`, `guides/`, or `reference/` only when they are stable and likely to recur.
+   - Remove or correct stable-doc claims that no longer match the current code.
+   - Promote lessons into `must/`, `guides/`, `architecture/`, or `reference/` only when they are stable and likely to recur.
    - Split docs aggressively instead of appending to large mixed files.
+   - Keep `llmdoc/memory/doc-gaps.md` reconciled by closing resolved gaps and adding only actionable new gaps.
+
+6. Run the active-memory archive check.
+   - After any new reflection is written, count active memory files under `llmdoc/memory/`, excluding `llmdoc/memory/lessons-learned.md`, `llmdoc/memory/doc-gaps.md`, and anything under `llmdoc/memory/archive/`.
+   - If the count is greater than 5, follow `skills/llmdoc/references/lessons-learned.md`: summarize recurring lessons into `llmdoc/memory/lessons-learned.md`, link each lesson to its source memory file, and move summarized raw memory into `llmdoc/memory/archive/YYYY-MM-DD/`.
+   - Treat hook reminders as best-effort only; this workflow step is the precise archive checkpoint.
 
-5. Synchronize `llmdoc/index.md`.
+7. Synchronize `llmdoc/index.md`.
    - Ensure changed docs are discoverable.
    - Keep reflections and decisions listed separately from stable docs.
+   - Do not index `.llmdoc-tmp/`.
 
-6. Report the reflection path and the stable docs that changed.
+8. Report the mode used, scratch report or reflection path when present, the archive action taken or skipped, and the stable docs that changed.
 
 At the end of a non-trivial task, proactively consider whether the user should be prompted to run this workflow.
diff --git a/skills/llmdoc/SKILL.md b/skills/llmdoc/SKILL.md
index d7e3f21..21cfa1c 100644
--- a/skills/llmdoc/SKILL.md
+++ b/skills/llmdoc/SKILL.md
@@ -38,6 +38,7 @@ Then load only the specific extras you need:
 - The main assistant, not `worker`, aligns with the user before non-trivial edits.
 - At the end of a non-trivial task, the main assistant should consider prompting for `/llmdoc:update`.
 - Temporary investigation artifacts live in `.llmdoc-tmp/`, not `llmdoc/memory/`.
+- `.llmdoc-tmp/` is a local temporary context cache. It may help nearby sessions, but it is ignored by git, not indexed, and not a source of truth.
 - `recorder` owns stable docs, `memory/decisions/`, and `memory/doc-gaps.md`. `reflector` owns `memory/reflections/`.
 
 ## Hook Support
diff --git a/skills/llmdoc/references/codex-cli-hooks.md b/skills/llmdoc/references/codex-cli-hooks.md
index a9486cc..2f40577 100644
--- a/skills/llmdoc/references/codex-cli-hooks.md
+++ b/skills/llmdoc/references/codex-cli-hooks.md
@@ -26,16 +26,19 @@ Good uses:
 
 ### `Stop`
 
-Use it for end-of-turn review or lightweight cleanup.
+Use it for end-of-turn review or lightweight cleanup. Treat it as a best-effort reminder, not as the precise memory archive checkpoint.
 
 Good uses:
 
 - append a stop-hook record into `.llmdoc-tmp/`
 - add lightweight review context after a turn ends
 - capture raw hook payloads for troubleshooting
+- remind the assistant that active memory may need archiving
 
 Do not expect `Stop` to replace end-of-task prompting inside the assistant. It runs at turn scope, not task scope.
 
+Do not rely on `Stop` to enforce the `lessons-learned.md` threshold exactly. `/llmdoc:update` must perform the exact active-memory count after any new reflection is written, because hook timing can miss boundary cases.
+
 ## Configuration
 
 Codex hooks are configured in `hooks.json` files such as:
diff --git a/skills/llmdoc/references/doc-structure.md b/skills/llmdoc/references/doc-structure.md
index 62b06a3..15a657d 100644
--- a/skills/llmdoc/references/doc-structure.md
+++ b/skills/llmdoc/references/doc-structure.md
@@ -10,13 +10,13 @@
 - `guides/`: one workflow per document
 - `reference/`: stable lookup facts, schemas, conventions, contracts
 - `memory/`: reflections, decisions, and doc gaps
-- `.llmdoc-tmp/`: temporary investigation scratch artifacts
+- `.llmdoc-tmp/`: local temporary context cache for scratch artifacts
 
 Why this split works:
 
 - stable docs stay small and reusable
 - transient notes stop polluting architecture docs
-- temporary reports can go stale without contaminating long-lived docs
+- temporary reports can go stale or disappear without contaminating long-lived docs
 
 ## Index responsibilities
 
@@ -53,6 +53,25 @@ Use this split:
 - Put mistakes and raw learnings in `memory/reflections/`, then promote only recurring stable lessons.
 - Keep temporary investigation reports in `.llmdoc-tmp/`, not in `llmdoc/memory/`.
 
+## Temporary Context Cache
+
+`.llmdoc-tmp/` is deliberately outside stable llmdoc.
+
+Use it for:
+
+- investigator scratch reports under `.llmdoc-tmp/investigations/`
+- hook logs or other local run artifacts
+- temporary handoff notes that may help the current or next nearby session
+
+Do not use it for:
+
+- current-state snapshots that should be trusted by future users
+- tracked project documentation
+- entries in `llmdoc/index.md`
+- durable decisions, reflections, or doc gaps
+
+Scratch reports may survive across sessions, but they are still temporary. Reuse them only after validating their recorded git revision, scope, and unresolved gaps against the current repository. If they are stale, delete or ignore them and investigate again.
+
 ## Recommended architecture slicing
 
 Prefer slicing by responsibility, ownership, or runtime flow.
diff --git a/skills/llmdoc/references/templates.md b/skills/llmdoc/references/templates.md
index d34ffee..a93a09a 100644
--- a/skills/llmdoc/references/templates.md
+++ b/skills/llmdoc/references/templates.md
@@ -144,6 +144,12 @@ Read related guides and reflections before editing when available.
 ```md
 # Investigation Scratch Report
 
+## Metadata
+- Date:
+- Git Revision:
+- Evidence Scope:
+- Reuse Conditions:
+
 ## Goal
 - What questions this scratch report answers.
 
@@ -156,4 +162,7 @@ Read related guides and reflections before editing when available.
 ## Promotion Notes
 - What should become stable docs.
 - What should stay temporary and be deleted later.
+
+## Gaps
+- What remains unresolved or needs fresh investigation before reuse.
 ```
diff --git a/skills/llmdoc/references/update-and-memory.md b/skills/llmdoc/references/update-and-memory.md
index 636b653..59e52e9 100644
--- a/skills/llmdoc/references/update-and-memory.md
+++ b/skills/llmdoc/references/update-and-memory.md
@@ -4,13 +4,26 @@
 
 When project knowledge changes, use `/llmdoc:update`.
 
+Tracked `llmdoc/` docs should describe the current repository. They should be smaller than the source code they describe, or add architectural intent, boundaries, and implementation reasoning that raw source search does not provide quickly.
+
+## Update modes
+
+Choose the lightest mode that keeps the docs correct:
+
+- `fast`: default after the coordinating assistant has just implemented the change. Use the fresh task summary, diff, targeted checks, and any still-valid local scratch reports.
+- `analysis`: use one focused evidence pass when current-state research, stale context, or unclear impact makes the update uncertain.
+- `full`: use separate investigation, reflection, and stable-doc maintenance when high risk, disputed facts, or process learning justify the extra independence.
+
+Escalate from `fast` only when the assistant cannot confidently name the impacted docs and facts.
+
 The update order is:
 
 1. rebuild task context
-2. investigate impacted concepts
-3. write reflection
-4. update stable docs
-5. sync `llmdoc/index.md`
+2. choose update mode
+3. investigate only when the mode requires it
+4. write reflection only when there is a workflow lesson or missing-doc signal
+5. update stable docs and reconcile `memory/doc-gaps.md`
+6. sync `llmdoc/index.md`
 
 Why reflection comes first:
 
@@ -18,6 +31,30 @@ Why reflection comes first:
 - missing-doc signals are easier to capture before they are rationalized away
 - stable docs should absorb only durable lessons, not raw frustration
 
+This does not mean every update needs a reflection. Routine `fast` updates can skip reflection when there was no process failure, repeated mistake, missing signal, or durable lesson.
+
+## Temporary investigation cache
+
+Investigation scratch belongs under `.llmdoc-tmp/investigations/`.
+
+These files are local temporary context cache:
+
+- they may survive across sessions
+- they are ignored by git and may be deleted
+- they are not indexed by `llmdoc/index.md`
+- they are evidence to validate, not project truth
+
+Each reusable scratch report should record enough context to decide whether it is still valid:
+
+- goal and concrete questions
+- date and git revision when available
+- evidence scope
+- conclusions
+- unresolved gaps
+- promotion candidates for tracked docs
+
+If the current repository no longer matches the scratch report's revision, scope, or assumptions, ignore it or redo the investigation.
+
 ## End-of-task update prompt
 
 At the end of a non-trivial task, the main assistant should actively evaluate whether the user should be prompted to run `/llmdoc:update`.
@@ -55,3 +92,5 @@ Read relevant reflections:
 
 Use `decisions/` for durable design or process decisions.
 Use `memory/doc-gaps.md` to track missing or weak documentation that should be improved later.
+
+During every non-trivial update, reconcile `memory/doc-gaps.md`: close gaps that the update resolved, mark stale gaps when the underlying concern no longer applies, and add only actionable new gaps with a clear closure condition.
diff --git a/skills/llmdoc/templates/stop.sh b/skills/llmdoc/templates/stop.sh
index 425ab55..a5e8f95 100755
--- a/skills/llmdoc/templates/stop.sh
+++ b/skills/llmdoc/templates/stop.sh
@@ -25,7 +25,7 @@ if [ "$active_memory_count" -gt 5 ]; then
 {
   "hookSpecificOutput": {
     "hookEventName": "Stop",
-    "additionalContext": "llmdoc active memory has ${active_memory_count} files, which exceeds the archive threshold of 5. During /llmdoc:update, summarize recurring lessons into llmdoc/memory/lessons-learned.md and archive summarized raw memory per skills/llmdoc/references/lessons-learned.md."
+    "additionalContext": "Best-effort reminder: llmdoc active memory currently has ${active_memory_count} files, which exceeds the archive threshold of 5. The precise checkpoint is /llmdoc:update after any new reflection is written; then summarize recurring lessons into llmdoc/memory/lessons-learned.md and archive summarized raw memory per skills/llmdoc/references/lessons-learned.md."
   }
 }
 EOF