reflect

复盘

会话结束前进行反思。重新阅读当前对话，找出遗漏和可能遗失的信息，并在会话结束前根据用户的选择采取行动。

范围与立场

• 仅限当前对话。 反思上下文中的对话。不要解析记录文件或 git 历史。这不是 gstack-retro（基于提交历史的复盘），也不是 gstack-learn（经验存储）——专注于推进后续行动。
• 假设会话结束后就此终止。 在此处确认的每条信息，如果没有写入文件、问题或 PR，就会消失。因此，留无处安放的知识是此技能的首要任务，而非附带事项：一个来之不易的注意事项，如果没有写进 CLAUDE.md，就会让下一次会话重复同一轮调试。
• 诚实面对上下文压缩。 如果会话经过压缩，反思仍保留的内容，并坦率说明。不要假装记得被概括掉的对话轮次。
• 默认不创建产物。 发现的问题留在对话中。列出的内容只是暂时的——用户可以回应，也可以忽略。只有当用户选择了会写入文件的操作，或明确提出要求时，才写入文件。
• 宁可少报，绝不刷屏。 错误标记一个“未完成事项”，或为一次性工作建议创建技能，都不如保持沉默。遵循下方的置信度门槛。拿不准时，就不要提。
• 提出建议前先核实。 未经检查，不要声称某项内容没有文档记录或没有跟踪。先阅读目标文件（CLAUDE.md、AGENTS.md、README.md），并先搜索未关闭的问题，确保提出的是真正需要修改现有内容的事项，而非重复已有条目。

第 1 步——反思

从头到尾重新阅读对话。标记任何事项之前，先把握完整脉络。

第 2 步——运行检测器

每个检测器都有严格的置信度门槛。未达到门槛的事项应直接舍弃，不作提示。

A. 未完成事项——用户跳过的待办事项或决定。

• 主要判断方法：找出助手在同一段中提出了两个或更多决定或问题的消息，然后检查用户的下一条回复是否回应了全部问题。例如，你问了三个问题，用户只回答了一个。未回应的问题是最有价值的发现——用户读到一大段文字的开头后就作出了回应，后面的内容可能根本没看见。
• 还要注意：明确提出“以后再做 X”、提出后再未跟进的 TODO，以及已承认但未修复的错误。
• 门槛：对话中有具体证据表明某事项曾被提出，但始终没有解决。

B. 文档缺口——因本次会话中的更改而过时的文档。

• 仅针对具体内容：“由于我们更改了 Y，README 中的 X 部分现在有误。”指出文件名和具体过时内容。
• 门槛：本次会话中做出的更改直接与现有文档描述的行为相矛盾。绝不要建议从头开始审查文档。

C. 技能化／工具链缺口——可交由新技能或 Agent 处理的重复工作，或值得整理成可复用技能的多步骤方案。

• 门槛：本次会话中该模式至少重复出现两次，或明显属于反复发生的工作。单次出现不符合条件。 D. CLAUDE.md / AGENTS.md 的缺漏 — 改进记忆文件。沿两个维度为每项发现标记：
• 范围： project（仓库本地的 CLAUDE.md/AGENTS.md）与 global（用户的 ~/.claude/CLAUDE.md）。根据偏好是特定于仓库，还是在所有地方都适用来选择。
• 类型：
  • 追加 → 用户明确持有但尚未记录的新原则、偏好或约定。
  • 改写 → 本次会话证明某条现有语句有误、已过时或会造成误解。引用当前内容并提出替换措辞——不要只是在原文上追加。
  • 钩子 → settings.json 钩子，而非文字。凡是“从现在起，每当发生 X，就执行 Y”这类内容，都是必须由框架自动执行的行为——不能作为记忆文件文本。采取行动时，应通过 update-config 技能处理。
• 判断标准：有明确证据表明用户持有此偏好——用户曾明确表示、纠正过你，或该偏好反复出现。一次性的风格选择不符合条件。

E. 无处安放的知识 — 本次会话确认的持久事实，目前只存在于这段对话中。

• 包括：费了功夫才发现的陷阱（除非先运行 X，否则构建会失败）、环境或工具限制、文档写错的外部 API 实际情况、尝试后被否决的方案及其原因、某项决策及其理由、某段代码采用当前写法的非显而易见原因。
• 被否决的方案与选定的方案同样值得记录。“我们试过 X，但因为 Y 而失败”正是如果不记录下来，下次会话就会重复尝试的内容。
• 判断标准，以下三项必须全部满足：（1） 发现它付出了实际代价——经历了失败尝试、调试循环、文档查阅，或用户将其作为事实提出；（2） 有人很可能会再次遇到；（3） 你已确认它尚未被记录。三十秒内就能查明的内容不符合条件。
• 然后使用下表将其归入适当位置。没有合理去处的内容不算发现。

F. 尚未交付的工作 — 仅存在于本次会话中，需要有一个持久的归属位置。

• 需要 PR： 工作区中或未推送分支上存在真实代码更改，且已足够完整，可以供人审查。判断标准：更改确实存在且结构完整——不是让你不好意思直接提交审查的半成品。
• 需要 issue： 本次会话发现的一项具体后续工作，但不会在本次完成。判断标准：具体到其他人可以直接接手（内容、原因和大致位置都明确），且尚未有人跟进——提出前先搜索未关闭的 issue。“以后应该改进错误处理”不符合条件；“parseConfig 吞掉了 YAML 错误并返回 {}——应将错误显式抛出，参见 config.ts:41”则符合。
• 切勿自行创建 issue 或 PR。一切都要像其他内容一样经过第 4 步。

知识应归于何处

将每项 D/E 发现准确归入一个位置。常见失误就是归错地方——把仓库特有的构建问题写进全局记忆文件，会影响所有其他项目。

知识内容……	归属位置
在所有仓库中都适用的偏好或习惯（语气、工具、工作流）	全局 ~/.claude/CLAUDE.md
Agent 在此仓库中需要遵循的约定或限制	项目 CLAUDE.md / AGENTS.md
人类贡献者或用户需要了解的内容——安装步骤、某项功能的用途、贡献者须知	README.md 或相关文档
与某个具体位置相关的代码设计原因	在适用位置添加代码注释
值得做但当前不会进行的工作	GitHub issue
已存在但其他人看不到的更改	commit + PR
反复执行的多步骤流程	新技能（检测器 C）
“从现在起，每当发生 X，就执行 Y”	通过 update-config 设置 settings.json 钩子

如果某项事实似乎适合两个位置，选择其受众真正需要的位置，然后继续。不要把同一句话重复写进三个文件。

步骤 3 — 汇总为一个扁平的排序列表

将所有检测器中通过门槛的发现汇总到内存中的一个扁平列表。保留每项发现的类别标签（A–F），但不要按类别对列表分组。

• 按价值 = 置信度 × 影响 × 持久性损失排序。第三个因素用于打破平局：如果两项发现同样出色，那么在本次会话结束后无法恢复的那项优先。只有这份对话记录中才有的注意事项，优先级高于任何人之后都能从代码中发现的文档改动。
• 先合并，再排序。 两项发现若要写入同一个目标文件，就合并为一项发现、一个问题、一次编辑。
• 选出前 5 项。 丢弃其余项。如果通过门槛的发现超过 5 项，用一行说明（例如“已舍弃 3 项置信度较低的内容”），让用户知道还有其他内容，但不要展示它们。
• 如果没有任何内容通过门槛，就说“没有值得标记的内容”，然后停止。

步骤 4 — 一次询问一项发现

将入围项按顺序作为彼此独立的单选 AskUserQuestion 问题提出，每项发现一个问题，让最有力的建议排在最前面。不要将多项发现捆绑到一个 multiSelect 问题中；这样会妨碍选择。每项发现都应单独决定。

每项发现的问题应符合以下要求：

• header：类别标签 — “未完成事项”、“文档缺口”、“技能化”、“CLAUDE.md”、“知识”或“发布”。
• question：具体说明发现（遗漏了什么／什么内容已过时／会丢失什么／应打开什么），指出目标位置，然后询问要如何处理。
• options（单选，multiSelect: false）：将推荐操作放在首位，并标记为“（推荐）”。接下来列出合理的备选项，最后提供明确的拒绝选项。各类别通常建议的操作如下：
  • A（未完成事项）：“现在完成”——如果工作量较大，则选“完成最小的下一步”。
  • B（文档缺口）：“显示差异并应用”。
  • C（技能化）：“起草 SKILL.md 框架”。
  • **D（CLAUDE.md/AGENTS.md）：**追加／重写 → “显示编辑内容并应用”；钩子 → “通过 update-config 接入钩子”。
  • E（知识）：“立即写入 <目标位置>”。如果目标位置确实有争议，备选项应列出其他目标位置，而不是同一操作的模糊版本。
  • F（发布）：“开启 PR”／“提交 issue”——创建前先展示拟定的标题和正文。
  • 始终将“跳过”／“保留不动”作为最后一个选项。

一次询问一项（也可以每次提几个问题，但每个问题只能涉及一项发现）。这样就能在继续之前，根据每个回答采取行动。

步骤 5 — 根据每项选择采取行动

对于用户选择要处理的每项发现，立即在本次会话中执行：

• **A（未完成事项）：**完成遗漏的事项；如果工作量较大，则确认最小的下一步。
• **B（文档缺口）：**生成准确的差异，并在获得批准后应用。
• **C（技能化）：**起草 SKILL.md 框架或建议使用 /gstack-skillify。不要强行在 /reflect 中完成整个技能；先提供存根或推迟处理即可。
• **D（CLAUDE.md/AGENTS.md）：**追加／重写 → 显示确切的记忆文件差异（重写时引用旧行），并在获得批准后应用；钩子 → 调用 update-config 将其接入。
• **E（知识）：**将其作为针对当前文件的实际差异，写入经路由确定的目标位置；措辞、章节结构和详细程度应符合该文件现有风格。只保留事实及其影响；简洁、持久的一行胜过一段会话叙述。绝不要将对话记录粘贴到记忆文件中。
• **F（发布）：**PR → 如果可用则交由 /gh-pr 处理，否则提交更改、推送并使用拟定的标题和正文开启 PR。Issue → 使用拟定的标题和正文创建，并在仓库中读者会查找它的位置添加链接。先展示草稿；只有在用户批准后才创建。

除非用户选择了会写入内容的操作，或明确要求留下书面记录，否则不要将任何内容持久化到磁盘。