trace

Trace 技能

**快速参考：**通过 CASS 会话、交接记录、git 和制品追溯设计决策。输出：.agents/research/YYYY-MM-DD-trace-*.md

必须执行此工作流。不要只描述它。

适用场景

• 追溯架构决策的演变过程
• 查明某个概念何时引入
• 了解某种设计的原因
• 为设计决策构建溯源链

对于知识制品的溯源（学习成果、模式、层级），请改用 $curate --mode=provenance。

**CLI 依赖项：**cass（会话搜索）。如果 cass 不可用，请跳过对话记录搜索，并依靠 git log、交接文档和 .agents/ 制品追溯决策。

执行步骤

给定 /trace <concept>：

步骤 1：对目标类型分类

确定要追溯哪种类型的来源：

IF target is a file path (contains "/" or "."):
  → Use `$curate --mode=provenance` (artifact lineage)

IF target is a git ref (sha, branch, tag):
  → Use git-based tracing (Step 2b)

ELSE (keyword/concept):
  → Use design decision tracing (Step 2a)

步骤 2a：设计决策追溯（概念）

启动 4 个并行搜索 Agent（CASS、Handoff、Git、Research），并等待全部完成。

**后端：**Agent 使用 Task(subagent_type="Explore")，在 OpenCode 中映射为 task(subagent_type="explore")。请参阅 skills/shared/SKILL.md（“Runtime-Native Spawn Backend Selection”），了解共享约定。

阅读 references/discovery-patterns.md，查看 Agent 定义和提示词。

步骤 2b：基于 Git 的追溯（提交/引用）

阅读 references/discovery-patterns.md，查看基于 git 的追溯命令。

步骤 3：构建时间线

将所有来源的结果合并为一条按时间顺序排列的时间线（从最早开始）。对同一天、同一会话的事件进行去重。每项陈述都必须附有来源引用。

步骤 4：提取关键决策

针对时间线中的每个事件，识别：

• **变更内容：**决策或演变
• **原因：**可用时说明推理依据
• **参与者：**会话/作者/提交作者
• **证据：**来源链接（会话路径、文件、提交）

步骤 5：撰写追溯报告

写入：.agents/research/YYYY-MM-DD-trace-<concept-slug>.md

阅读 references/report-template.md，了解完整的报告格式和去重规则。

步骤 6：向用户报告

告知用户：

1. 已成功追溯该概念
2. 演变时间线（关键日期）
3. 最重要的决策
4. 追溯报告的位置
5. 可进一步探索的相关概念

边缘情况处理

阅读 references/edge-cases.md，了解如何处理：没有 CASS 结果、没有交接记录、概念含糊（结果超过 20 条）以及所有来源都为空的情况。一般原则：继续使用其余来源，并在报告中注明缺失之处。

关键规则

• 搜索所有来源——CASS、交接记录、git、研究资料
• 构建时间线——目标是按时间顺序呈现演变过程
• 引用证据——每项陈述都必须有来源
• 妥善处理缺失信息——并非所有概念都会出现在所有来源中
• 撰写报告——追溯必须生成 .agents/research/ 制品

与制品溯源的关系

技能	用途	输入	输出
$curate --mode=provenance	制品溯源	文件路径	层级/晋升历史
/trace	设计决策	概念/关键词	演变时间线

遇到“这项学习成果源自何处？”时，使用 $curate --mode=provenance。 遇到“我们是如何决定采用这一架构的？”时，使用 /trace。

示例

# Trace a design decision
/trace "three-level architecture"

# Trace a role/concept
/trace "Chiron"

# Trace a pattern
/trace "brownian ratchet"

# Trace a feature
/trace "parallel wave execution"

追踪架构决策

用户说： /trace "agent team protocol"

执行过程：

1. Agent 将目标归类为概念（而非文件路径或 git 引用）
2. Agent 启动 4 个并行 Agent：CASS 搜索、交接搜索、git 日志搜索、研究材料搜索
3. CASS 找到 8 个提及“agent team”的会话，交接搜索找到 2 份文档，git 搜索找到 3 个提交，研究搜索找到 1 份分析
4. Agent 构建从 2026-01-15（首次提及）到 2026-02-08（最近更新）的时间线
5. Agent 提取 5 项关键决策：初始的 SendMessage 设计、添加 TeamCreate、审议协议、进程内模式、委派模式
6. Agent 将追踪报告写入 .agents/research/2026-02-13-trace-agent-team-protocol.md，其中包含完整时间线和引用

结果： 完整的演进时间线，展示了 agent team 协议如何在 7 个会话中逐步发展，并附有来源引用。

从 Git 提交追踪

用户说： /trace abc1234

执行过程：

1. Agent 检测到 git 引用格式（短 sha）
2. Agent 运行基于 git 的追踪命令，获取提交详情、变更文件和相关提交
3. Agent 使用 git log --grep 查找相关工作
4. Agent 在 .agents/ 中搜索同期的研究和计划
5. Agent 构建以该项特定变更为重点的时间线
6. Agent 编写报告，展示提交背景、变更内容及原因（依据提交消息和相关文档）

结果： 追踪报告将该提交与周边材料中的整体设计背景关联起来。

故障排除

问题	原因	解决方案
CASS 未返回结果	未安装会话搜索工具，或查询过于具体	检查 which cass。如果缺失，则跳过 CASS，依靠交接记录、git 和研究材料。尝试更宽泛的查询词。
时间线存在空缺	并非所有决策都记录在可搜索的材料中	在报告中注明空缺。建议采访团队成员，或查看 Slack/电子邮件存档以补充缺失的背景信息。
结果过多（匹配项 >50）	概念过于宽泛，或术语出现频率过高	阅读 references/edge-cases.md，了解如何处理含义不明确的概念。缩小查询范围或按日期范围筛选。请用户说明想追踪的具体方面。
追踪报告为空（所有来源均失败）	该概念确实没有文档记录，或存在拼写错误	核对拼写。尝试同义词。向用户说明：“未找到有记录的历史。这可能是一个新概念，也可能需要使用不同的搜索词。”

参考文档

• references/trace.feature — 可执行规范：目标类型路由、多来源并行搜索、带引用的时间线、关键决策提取、报告及空缺的优雅处理 (soc-qk4b)
• references/discovery-patterns.md — 搜索 Agent 定义和基于 git 的追踪命令
• references/report-template.md — 追踪报告格式和去重规则
• references/edge-cases.md — 空来源和含义不明确来源的处理