trace

Trace Skill

当问题模糊、涉及因果、证据密集，且目标是解释某个观察到的结果为什么发生时，而不是直接跳到修复或重写代码时，请使用此技能。

这是构建在内置 tracer agent 之上的编排层。目标是让追踪成为一种可复用的 OMC 操作通道：重述观察结果，生成相互竞争的解释，并行收集证据，对解释进行排序，并提出能最快消除不确定性的下一步探测。

适合的入口场景

当问题具有以下特征时，请使用 /oh-my-claudecode:trace：

• 模糊
• 涉及因果
• 证据密集
• 最适合通过并行探索相互竞争的解释来回答

示例：

• 运行时 bug 和回归
• 性能 / 延迟 / 资源行为
• 架构 / premortem / postmortem 分析
• 科学或实验结果追踪
• 配置 / 路由 / 编排行为解释
• “给定此输出，追溯可能的原因”

核心追踪契约

始终保留以下区分：

1. 观察 -- 实际观察到的内容
2. 假设 -- 相互竞争的解释
3. 支持证据 -- 支持每种解释的内容
4. 反对证据 / 缺口 -- 与之矛盾或仍然缺失的内容
5. 当前最佳解释 -- 目前领先的解释
6. 关键未知 -- 使排名靠前的解释彼此区分开的缺失事实
7. 判别性探测 -- 用于消除不确定性的最高价值下一步

不要退化为：

• 通用的修复式编码循环
• 通用的调试器摘要
• worker 输出的原始转储
• 在证据不完整时假装确定

证据强度层级

将证据视为有等级之分，而非平面等权。

从最强到最弱：

1. 受控复现 / 直接实验 / 具有唯一判别力的产物
2. 具有紧密来源追踪的一手产物（trace 事件、日志、指标、基准输出、配置、git 历史、file:line 行为）
3. 多个独立来源汇聚到同一解释
4. 单来源代码路径或行为推断
5. 弱间接线索（时序、命名、堆栈顺序、与既往 bug 的相似性）
6. 直觉 / 类比 / 猜测

当存在更强的矛盾证据时，明确下调主要依赖较低层级证据的假设的排名。

强证伪 / 反证规则

每一次严肃的 /trace 运行都必须尝试证伪自己最偏好的解释。

对于每个排名靠前的假设：

• 收集支持它的证据
• 收集反对它的证据
• 说明它做出的独特预测
• 说明哪些观察会难以与它协调一致
• 找出能将它和次优替代解释区分开的最低成本探测

在以下情况下下调某个假设的排名：

• 直接证据与之矛盾
• 它只能通过添加新的未验证假设来维持
• 与竞争者相比，它没有做出独特预测
• 更强的替代解释能以更少假设解释相同事实
• 它的支持主要来自间接线索，而竞争者有更强的证据层级

团队模式编排形态

对 /trace 使用 Claude 内置团队模式。

负责人应：

1. 精确重述观察到的结果或“为什么”问题
2. 提取追踪目标
3. 生成多个刻意不同的候选假设
4. 在团队模式下默认生成 3 条 tracer 通道
5. 为每条通道分配一个 tracer worker
6. 指示每个 tracer worker 收集支持和反对其通道的证据
7. 在领先假设与最强剩余替代解释之间进行反驳轮
8. 检测排名靠前的通道是真的不同，还是实际上收敛到同一根因
9. 将发现合并为带有明确关键未知和判别性探测的排序综合结论

重要：worker 应追求刻意不同的解释，而不是并行追求同一解释。

v1 的默认假设通道

除非提示词强烈暗示存在更好的划分方式，否则使用以下 3 条默认通道：

1. 代码路径 / 实现原因
2. 配置 / 环境 / 编排原因
3. 测量 / 产物 / 假设不匹配原因 — 涵盖验证方法缺陷，而不仅仅是系统缺陷。示例：验证查询在多个不同实体、租户、流或组之间复用了同一个维度键；比较过滤器的形态与 schema 粒度不匹配；或者在没有枚举的情况下假设目录或列名可在不同运行时之间移植。这包括多实体前提 / 关键假设不匹配。

对于通道 3，跨实体差异在升级之前需要进行前提审计：枚举实体维度，并检查零行或不匹配结果是来自将同一个键应用于多个实体，而不是来自系统缺陷；结果可能是验证方法缺陷。

这些默认通道有意设置得很宽泛，以便第一轮切片可适用于 bug、性能、架构和实验追踪。

强制交叉检查视角

在初始证据收集之后，在相关时用以下视角对领先假设进行压力测试：

• 系统视角 -- 队列、重试、背压、反馈回路、上游 / 下游依赖、边界故障、协调效应
• 事前验尸视角 -- 假设当前最佳解释不完整或错误；什么样的故障模式会在之后让这次追踪难堪？
• 科学视角 -- 对照、混杂因素、测量偏差、替代变量、可证伪预测

这些视角不是填充内容。当它们能够揭示遗漏的解释、隐藏的依赖或薄弱的推断时，就使用它们。

Worker 契约

每个 worker 都应是 tracer 通道负责人，而不是通用执行者。

每个 worker 必须：

• 正好负责一条假设通道
• 明确复述其通道假设
• 收集支持该通道的证据
• 收集反对该通道的证据
• 对其论据背后的证据强度进行排序
• 指出缺失的证据、失败的预测和剩余的不确定性
• 指出该通道的关键未知项
• 推荐该通道最佳的具体判别性探针
• 避免塌缩到实现层面，除非被明确要求这样做

有用的证据来源包括：

• 相关代码、测试、配置、文档、日志、输出和基准产物
• 通过 trace_timeline 获取的现有追踪产物
• 通过 trace_summary 获取的现有聚合追踪证据

推荐的 worker 返回结构：

1. 通道
2. 假设
3. 支持证据
4. 反对证据 / 缺口
5. 证据强度
6. 关键未知项
7. 最佳判别性探针
8. 置信度

Leader 综合契约

最终的 /trace 答案应当进行综合，而不仅仅是拼接。

返回：

1. 观察到的结果
2. 排序后的假设
3. 按假设划分的证据摘要
4. 反对证据 / 缺失证据
5. 反驳轮
6. 收敛 / 分离说明
7. 最可能的解释
8. 关键未知项
9. 推荐的判别性探针
10. 其他追踪通道（可选，仅当不确定性仍然很高时）

即使某个解释目前占主导地位，也要保留一份排序后的候选清单。

反驳轮与收敛检测

在结束追踪之前：

• 让最强的非领先通道对当前领先者提出其最佳反驳
• 迫使领先者用证据而非断言来回应反驳
• 如果反驳实质性削弱了领先者，则重新排列表格
• 如果两个“不同”的假设归结为同一个底层机制，则合并它们并明确说明
• 如果两个假设仍然暗示不同的下一步探针，则即使它们听起来相似，也要将它们分开

不要仅仅因为多个 worker 使用相似措辞就声称收敛。收敛需要满足以下之一：

• 相同的根本因果机制，或
• 独立证据流指向同一个解释

明确的降级指引

负责人应明确说明某个假设为何被降级：

• 被更强的证据反驳
• 缺少它所预测的观察结果
• 需要额外的临时假设
• 解释的事实少于领先假设
• 在反驳环节中落败
• 收敛为更强的父级解释

这一点很重要，因为 /trace 应教会读者为什么一种解释比另一种更胜一筹，而不只是呈现最终表格。

建议的负责人提示词骨架

使用类似这样的团队导向编排提示词：

1. “精确复述观察结果。”
2. “生成 3 个刻意不同的假设。”
3. “使用 Claude 内置团队模式，为每个假设创建一个追踪通道。”
4. “对每个通道，收集支持和反对的证据，对证据强度排序，并指出关键未知项及最佳判别性探针。”
5. “如有帮助，对领先假设应用系统、预mortem 和科学视角。”
6. “在排名前两位的解释之间进行一轮反驳。”
7. “返回排序后的解释表、收敛说明、关键未知项，以及单个最佳判别性探针。”

输出质量标准

优质的 /trace 输出应：

• 有证据支撑
• 简洁但严谨
• 对过早的确定性持怀疑态度
• 明确说明缺失的证据
• 对下一步行动具有实用性
• 明确说明较弱的解释为何被降级

最终综合示例形态

观察到的结果

[发生了什么]

排序后的假设

排名	假设	置信度	证据强度	为何领先
1	...	高 / 中 / 低	强 / 中 / 弱	...

各假设的证据摘要

• 假设 1：...
• 假设 2：...
• 假设 3：...

反对证据 / 缺失证据

• 假设 1：...
• 假设 2：...
• 假设 3：...

反驳环节

• 对领先假设的最佳反驳：...
• 领先假设为何成立 / 失败：...

收敛 / 分离说明

• ...

最可能的解释

[当前最佳解释]

关键未知项

[使不确定性保持开放的唯一缺失事实]

建议的判别性探针

[单个下一步探针]

附加追踪通道

[仅在不确定性仍然很高时]