| name | repomind-summary |
| description | 每次 AI 完成代码修改、问答或排查结论后，且最终答复前，必须同步做轻量 summary gate 判断；代码写完后也要自动进入 gate。只有发现可复用的新业务知识、用户纠错、手动要求记忆的经验、模块边界、排查经验或知识文档元数据变化时，才执行写入。按类型更新 concepts、modules、troubles 及每个文档自己的 name/description，避免回到集中式索引。 |
| metadata | {"short-description":"把可复用知识写回 RepoMind"} |
RepoMind 编码 / 问答 / 排查后更新
执行语义：本 skill 必须同步完成。
- 调用方不能把它当后台任务，也不能在它完成前先回复用户
- AI 完成代码修改、生成文件、修复 bug 或跑完验证后，最终答复前也必须进入本 skill 的 summary gate
- 如果调用方只是口头说“summary 正在运行”但没有真正执行到清理和摘要输出，这视为流程失败
- 本 skill 完成的标志是：知识库更新/判定结束 + 清理
.query-findings.json + 输出 summary 摘要
核心原则
- 先做 summary gate，只有值得沉淀才写文件。
- RepoMind 不再维护
index.json；路由元数据写在各知识文档自己的 frontmatter。
- 每次进入 summary，都要优先检查索引元数据；
description 是首要检索摘要，modules 的 keywords 是辅助定位词。
- 只记录“代码不会直接告诉你的东西”。
- 用户纠正业务事实、模块归属、入口位置、排查根因或历史结论时，视为用户确认的修订证据，必须进入完整 summary 流程。
- 用户明确要求“记一下 / 总结到知识库 / 以后遇到这个要注意 / 这个经验要沉淀”时，视为手动沉淀请求，必须进入完整 summary 流程。
步骤 0：先修正旧格式
每次进入 summary 前先执行：
repomind kb-migrate
如果历史文件还是旧格式，这一步先修复，然后再继续更新。
步骤 1：执行 summary gate
先回答四个问题：
| 问题 | 判断 |
|---|
| 是否有新知识 | ✅/❌ |
| 是否可复用 | ✅/❌ |
| 是否有证据 | 用户确认 / 当前代码 / 排查结果 / 现有知识库 |
| 推荐写入目标 | concepts / modules / troubles / discard |
gate 不通过时，直接输出“无需更新”，不要写文件。
这里的“新知识”不只包括业务规则，还包括：
- 现有模块文档没有覆盖到的关键入口
- 现有模块关键词没有覆盖到的常见搜索词/别称
- 现有模块文档没有写出的常见修改场景
也就是说：只要本轮代码查找暴露出 RepoMind 路由缺口，这本身就是需要 summary 的新知识。
但是以下场景默认 gate 通过，必须进入完整 summary 流程：
- 本轮有业务代码修改
- 本轮有业务/排查/PRD 相关结论
- 本轮用户纠正了业务事实、模块归属、入口位置、排查根因或历史结论，例如“X 才是”“Y 错了”“不是 A，是 B”
- 本轮用户明确要求沉淀知识，例如“记一下”“总结到知识库”“以后遇到这个要注意”“这个经验要沉淀”
- 本轮为了定位代码，绕过了现有
modules 文档，转而直接查 graphify/source/rg
- 本轮识别出应该新增、删除或收紧某个模块的
keywords
步骤 2：读取待处理发现
优先读取：
cat .repomind/.query-findings.json 2>/dev/null || echo '{"needs_summary": false}'
如果没有这个文件，但本轮问答/排查确实形成了新知识，就按同样格式自行生成一个临时发现文件再继续。
如果没有这个文件，但用户在本轮明确纠正了旧说法，就按同样格式自行生成临时发现文件，并至少记录：
- 旧说法
- 新说法
- 证据来源（用户确认 / 当前代码 / 排查结果 / 现有知识库）
- 影响范围（concept / module / trouble）
如果没有这个文件，但用户明确要求“记一下 / 总结到知识库 / 以后遇到这个要注意 / 这个经验要沉淀”，就按同样格式自行生成临时发现文件，并至少记录：
- 用户要求沉淀的原始要点
- 这条知识的复用场景
- 证据来源（用户确认 / 当前代码 / 排查结果 / 现有知识库）
- 推荐写入目标（concept / module / trouble）
如果本轮存在“直接查代码才完成定位”的情况，即使 .query-findings.json 还没写，也必须自行补一份临时发现文件，至少包含一条 module_knowledge。
兼容旧类型时，先做归一化：
new_business_card / new_business_rule → concept_knowledgemodule_update / new_code_location / index_knowledge → module_knowledgetrouble_record → trouble_knowledge
步骤 3：先读取元数据，再定位要改的文档
执行：
repomind kb-metadata
然后按 name / description 决定要打开哪些知识文档；对 modules 还要同时看 keywords。
不要直接全量打开所有 concepts/*.md、modules/*.md、troubles/*.md。
进入正文合并前，先单独判断：
- 这次发现是否改变了文档的适用场景、业务边界、典型现象或常见叫法
- 如果改变了，即使正文只改一点点，也要优先刷新 frontmatter 元数据
知识写入边界
concepts
写：
- 业务定义
- 存在目的
- 用户侧表现
- 数据流
- 核心规则和边界
- 易混淆概念
不写：
frontmatter description 必须覆盖：
- 这个概念是什么
- 它会在哪些场景出现
- 它和什么最容易混淆，或主要边界是什么
modules
写：
- 模块职责变化
- 关键入口
- 常见修改场景
- AI 注意事项
- 跨模块约束和隐性依赖
不写：
- 函数内部伪代码
- 长调用链
- 代码里 30 秒内能直接读到的普通事实
frontmatter description 必须覆盖：
frontmatter keywords 必须覆盖：
- 模块名、常见别称、英文名或缩写
- 最常拿来搜它的业务词或入口词
- 只放 3-8 个判别词，不堆泛词
troubles
写：
frontmatter description 必须覆盖：
步骤 4：分拣发现类型
把发现分成三类：
| 类型 | 写入目标 |
|---|
concept_knowledge | .repomind/concepts/*.md |
module_knowledge | .repomind/modules/*.md |
trouble_knowledge | .repomind/troubles/*.md |
如果只是一次性上下文、纯代码显式信息或证据不足，归为 discard。
在分拣完成后，先做一次“元数据总结”：
- 哪些文档的
description 应该重写或收紧
- 哪些模块文档的
keywords 应该新增、删除或去重
- 即使正文改动很小，只要索引入口词变了，也必须优先更新元数据
- 如果本轮代码定位绕过了现有模块文档，也必须把“为什么没命中”“缺了什么关键词/入口词”总结到这里
- 如果本轮是用户纠错，必须判断被修正的是概念边界、模块归属、关键入口还是排查根因，并把旧说法与新说法写入对应文档的正文或修订记录
- 如果本轮是手动沉淀请求，必须判断它更像业务概念、模块修改经验还是排查经验；只写入 concepts/modules/troubles，不创建新的集中式导览或索引文档
步骤 5：更新知识文档
5a：concepts
模板：
---
name: "Pro 角色"
description: "高级用户身份概念。用于判断权益范围、典型触发场景，以及和 VIP 的区别。"
---
# 概念：Pro 角色
## 是什么
（一句话业务定义，回答“这个概念本身是什么”）
## 为什么有
（业务目的、产品背景、历史原因；没有证据就写“待确认”）
## 用户侧表现
（用户在哪些页面/流程/操作里能感知到它，表现为什么）
## 系统侧数据流
（数据从哪里来，经过什么处理，最终在哪里消费）
## 核心规则
（稳定规则、边界条件、负向规则；按主题合并，不抄实现分支）
## 易混淆概念
（它不是什么、和谁容易混、边界差异是什么）
规则：
- 无卡片 + 有稳定业务语义 → 新建
- 有卡片 + 新增业务规则/边界/预期 → 合并
- 只是实现调整 → 不更新正文，但说明原因
- 用户纠正业务定义、业务规则、边界或易混淆概念 → 合并为当前有效结论，并保留必要的修订说明
- 如果卡片更新后适用场景或边界变化，必须同步改
description
- 每次 summary 都要问一句：当前
description 是否仍能让模型在首轮路由时命中这张卡；如果不能，先改 description
5b：modules
模板：
---
name: "支付模块"
description: "支付与退款相关模块。用于定位下单、回调、补偿入口和改动影响面。"
keywords:
- "支付"
- "payment"
- "退款"
- "refund"
- "回调"
---
# 支付模块
## 业务描述
（1-3 句话描述模块在业务上负责什么，不要变成目录树说明）
## 关键代码
（列真正该看的入口文件/函数，并说明为什么从这里开始）
## 常见修改场景
（列未来最常见需求的下手点，例如“改退款规则先看哪里”）
## AI 注意事项
（写隐性约束、跨模块联动、业务坑点、容易误改的地方）
规则：
- 只保留有复用价值的模块知识
- 优先维护
AI 注意事项
- 关键代码按文件路径去重；需要时再细到函数名
- 如果模块职责、入口范围、影响面发生变化，frontmatter
description 必须同步更新
- 如果模块新增别称、核心入口词、常见搜索词或业务叫法变化，frontmatter
keywords 必须同步更新
- 用户纠正模块归属、关键入口或常见叫法时，必须同步更新
关键代码、常见修改场景 或 keywords
description 写不下的检索词，不要硬塞进句子，放进 keywordskeywords 以命中率为目标，不以完整性为目标；去掉噪音词，保留最能区分该模块的词- 如果本轮是靠直接源码/图谱搜索才找到该模块实现，必须反向补齐模块文档：
- 补入口文件/函数
- 补常见修改场景
- 补能帮助首轮命中的
keywords
- 如有必要，收紧
description
5c：troubles
模板：
---
name: "VIP 延迟生效"
description: "处理 VIP 购买后权益未及时生效时查看。包含首查方向和常见根因。"
---
# 排查：VIP 延迟生效
## 当前状态
（写这条排查记录当前是否仍有效，例如“有效 / 已修正 / 已过期 / 待验证”）
## 问题
（用用户可感知的语言描述现象，回答“到底出了什么问题”）
## 排查路径
（按顺序写排查步骤，回答“第一次接手时应该先查什么、后查什么”）
## 根因
（写当前有效根因；如果旧结论被推翻，这里放最新结论）
## 验证方式
（写如何确认问题是否存在、修复是否生效，例如日志、数据对比、接口观察点）
## 涉及模块
（列相关业务模块，帮助后续从 trouble 跳到 module）
## AI 注意事项
（写最容易漏掉的判断条件、版本差异、历史坑点）
## 修订记录
（按时间记录什么时候新增、修正、失效，为什么改）
规则：
- 无相似记录 → 新建
- 旧结论仍有效 → 合并新证据
- 旧结论已过时 → 修正当前有效结论，并保留修订记录
- 如果问题的典型症状或首查方向发生变化，frontmatter
description 也要更新
步骤 6：清理与校验
写完后执行：
repomind kb-metadata
rm -f .repomind/.query-findings.json
目的是确认：
- 所有新增/修改文档都暴露了正确的
name / description
- 所有模块文档都暴露了当前有效的
keywords
- 没有回写旧的集中式索引
步骤 7：输出摘要
摘要必须包含：
- Summary gate 结果
- 哪些发现被写入，哪些被丢弃
- concept/module/trouble 各自的更新动作
- 哪些文档的 frontmatter 元数据被同步调整
- 哪些模块关键词被新增、删除或去重
- 如果本轮有绕过模块文档的直接代码查找，必须写明：
- 绕过了哪个模块或哪个缺口
- 本次补回了哪些入口信息
- 本次补回了哪些关键词
建议格式：
## RepoMind 更新摘要
### Summary Gate
- 是否有新知识：...
- 是否可复用：...
- 写入目标：...
### 知识写入路由
- 概念 A → concepts/xxx.md
- 模块 B → modules/xxx.md
- 排查 C → troubles/xxx.md
- 丢弃 D → 原因
### 元数据同步
- concepts/xxx.md：更新 description，补充适用场景
- modules/yyy.md：更新 description，补充影响面
- modules/yyy.md：更新 keywords，补充新的搜索词 / 别称 / 入口词
