用途
Trace 是一个用于追溯设计决策演变过程的技能。它的目标是回答以下类型的问题：
- 某个架构决策是如何一步步演变而来的（HOW）
- 某个概念是在什么时候被引入的（WHEN）
- 某个设计为什么采用某种方式（WHY）
- 为设计决策构建完整的来源链（provenance chain）
注意：如果需要追溯的是知识产物（learnings、patterns、tiers）的血统来源，应改用 $curate --mode=provenance，而不是本技能。
主要能力
- 多源并行检索：同时从 CASS 会话、交接文档、git 记录、研究产物四个来源搜索相关信息
- 目标类型分类：根据输入判断是文件路径、git 引用还是概念关键词，并选择对应的追溯路径
- 时间线构建：将各来源结果合并为按时间排序（最早在前）的单一时间线，并对同日/同会话事件去重
- 关键决策提取：对时间线中的每个事件识别“改变了什么”“为什么”“谁”“证据链接”
- 报告输出：生成带来源引用的追溯报告，写入 .agents/research/YYYY-MM-DD-trace-<concept-slug>.md
使用方式
基本调用形式为 /trace <concept>，例如：
- /trace "three-level architecture"（追溯一个设计决策）
- /trace "Chiron"（追溯一个角色/概念）
- /trace "brownian ratchet"（追溯一个模式）
- /trace "parallel wave execution"（追溯一个功能）
- /trace abc1234（从 git 提交追溯）
执行流程：
- 分类目标类型：若目标是文件路径（含 "/" 或 "."），改用 $curate --mode=provenance；若目标是 git 引用（sha、分支、标签），走基于 git 的追溯；否则按概念走设计决策追溯。
- 设计决策追溯：启动 4 个并行搜索代理（CASS、Handoff、Git、Research），等待全部完成。代理使用 Task(subagent_type="Explore")，在 OpenCode 中映射为 task(subagent_type="explore")。
- 构建时间线：合并所有来源结果，按时间排序，去重，每条主张都需附来源引用。
- 提取关键决策：识别变化内容、原因、相关方、证据链接。
- 撰写追溯报告：写入 .agents/research/YYYY-MM-DD-trace-<concept-slug>.md。
- 向用户汇报：说明追溯成功、演变时间线（关键日期）、最重要的决策、报告位置、可继续探索的相关概念。
CLI 依赖：cass（会话搜索）。若 cass 不可用，则跳过会话记录搜索，仅依赖 git log、交接文档和 .agents/ 产物进行追溯。
适用场景
- 追溯某个架构决策的完整演变过程
- 查找某个概念首次被引入的时间点
- 理解某项设计背后的原因
- 为设计决策建立来源链
- 从某个 git 提交出发，还原其上下文与相关设计背景
限制与边界情况
- CASS 无结果：可能是会话搜索未安装或查询过于具体；可检查 which cass，缺失时跳过 CASS，改用交接文档/git/研究产物，并尝试更宽泛的查询词。
- 时间线存在缺口：并非所有决策都有可检索的记录；应在报告中标注缺口，并建议访谈团队成员或查阅 Slack/邮件归档。
- 结果过多（超过 50 条匹配）：概念过于宽泛或词频过高；可缩小查询范围或按日期过滤，并向用户询问更具体的追溯方向。
- 报告为空（所有来源均失败）：概念可能确实无记录或拼写有误；应核对拼写、尝试同义词，并向用户说明“未找到有记录的历史，这可能是新概念或需要更换搜索词”。
- 通用原则：继续使用剩余可用来源，并在报告中注明缺口。
关键规则
- 搜索所有来源：CASS、交接文档、git、研究产物
- 构建时间线：以按时间顺序的演变为目标
- 引用证据：每条主张都需要来源
- 优雅处理缺口：并非所有概念都存在于所有来源中
- 必须产出报告：追溯必须生成 .agents/research/ 下的产物
与产物血统追溯的关系
- $curate --mode=provenance：用于产物血统，输入为文件路径，输出为层级/晋升历史，适合回答“这个 learning 从哪来？”
- /trace：用于设计决策，输入为概念/关键词，输出为演变时间线，适合回答“我们是如何决定这个架构的？”
参考文档
- references/trace.feature — 可执行规范：目标类型路由、多源并行搜索、带引用的时间线、关键决策提取、报告与缺口处理
- references/discovery-patterns.md — 搜索代理定义与基于 git 的追溯命令
- references/report-template.md — 追溯报告格式与去重规则
- references/edge-cases.md — 空/模糊来源的处理方式