repomind-summary

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 摘要

核心原则

1. 先做 summary gate，只有值得沉淀才写文件。
2. RepoMind 不再维护 index.json；路由元数据写在各知识文档自己的 frontmatter。
3. 每次进入 summary，都要优先检查索引元数据；description 是首要检索摘要，modules 的 keywords 是辅助定位词。
4. 只记录“代码不会直接告诉你的东西”。
5. 用户纠正业务事实、模块归属、入口位置、排查根因或历史结论时，视为用户确认的修订证据，必须进入完整 summary 流程。
6. 用户明确要求“记一下 / 总结到知识库 / 以后遇到这个要注意 / 这个经验要沉淀”时，视为手动沉淀请求，必须进入完整 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_knowledge
• module_update / new_code_location / index_knowledge → module_knowledge
• trouble_record → trouble_knowledge

步骤 3：先读取元数据，再定位要改的文档

执行：

repomind kb-metadata

然后按 name / description 决定要打开哪些知识文档；对 modules 还要同时看 keywords。

不要直接全量打开所有 concepts/*.md、modules/*.md、troubles/*.md。

进入正文合并前，先单独判断：

• 这次发现是否改变了文档的适用场景、业务边界、典型现象或常见叫法
• 如果改变了，即使正文只改一点点，也要优先刷新 frontmatter 元数据

知识写入边界

concepts

写：

• 业务定义
• 存在目的
• 用户侧表现
• 数据流
• 核心规则和边界
• 易混淆概念

不写：

• SQL、字段、函数步骤、调用链

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 写不下的检索词，不要硬塞进句子，放进 keywords
• keywords 以命中率为目标，不以完整性为目标；去掉噪音词，保留最能区分该模块的词
• 如果本轮是靠直接源码/图谱搜索才找到该模块实现，必须反向补齐模块文档：
  • 补入口文件/函数
  • 补常见修改场景
  • 补能帮助首轮命中的 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，补充新的搜索词 / 别称 / 入口词