trace

Trace Skill

用途

当问题具有模糊、因果性强、证据密集等特征，且最佳回答方式是并行探索相互竞争的解释时，使用此技能。它不直接跳入修复或重写代码，而是解释已观察到的结果为何发生。

适用入口场景

使用 /oh-my-claudecode:trace 的典型问题包括：

• 运行时缺陷与回归
• 性能 / 延迟 / 资源行为
• 架构 / 事前分析 / 事后分析
• 科学或实验结果追踪
• 配置 / 路由 / 编排行为解释
• “给定这个输出，回溯可能的原因”

核心追踪契约

始终保留以下区分：

• 观察 -- 实际观察到的内容
• 假设 -- 相互竞争的解释
• 支持证据 -- 支撑每种解释的内容
• 反对证据 / 缺口 -- 与之矛盾或仍然缺失的内容
• 当前最佳解释 -- 当前领先的解释
• 关键未知 -- 使排名靠前的解释无法区分的那项缺失事实
• 区分性探测 -- 为消除不确定性而进行的最高价值下一步

不要退化为：

• 通用的修复型编码循环
• 通用调试器摘要
• worker 输出的原始倾倒
• 证据不完整时的虚假确定性

证据强度层级

证据应被视为有等级而非平铺。由强到弱：

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

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

强证伪 / 反证规则

每次严肃的 /trace 运行都必须尝试证伪自己最偏好的解释。对每个靠前假设：

• 收集支持它的证据
• 收集反对它的证据
• 陈述它做出的独特预测
• 陈述哪种观察难以与它调和
• 找出能将其与次优替代方案区分开来的最廉价探测

在以下情况降低假设排名：

• 直接证据与之矛盾
• 它仅靠添加新的未经验证假设而存活
• 与竞争者相比，它没有做出独特预测
• 更强的替代方案以更少假设解释了相同事实
• 其支持主要来自间接线索，而竞争者拥有更强证据层级

团队模式编排形态

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

主导者应：

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

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

v1 默认假设通道

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

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

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

这些默认通道有意保持宽泛，使首轮切片可跨缺陷、性能、架构和实验追踪使用。

强制交叉检查视角

初始证据收集之后，在相关时使用以下视角对领先者施压：

• 系统视角 -- 队列、重试、背压、反馈循环、上下游依赖、边界失败、协调效应
• 事前分析视角 -- 假设当前最佳解释不完整或错误；哪种失败模式会让此次追踪日后难堪？
• 科学视角 -- 对照、混杂因素、测量偏差、替代变量、可证伪预测

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

Worker 契约

每个 worker 应是 tracer 通道所有者，而非通用执行器。

每个 worker 必须：

• 只负责一条假设通道
• 明确重述其通道假设
• 收集支持该通道的证据
• 收集反对该通道的证据
• 对其论据背后的证据强度进行排序
• 指出缺失证据、失败预测与剩余不确定性
• 为其通道命名关键未知
• 推荐该通道最佳区分性探测
• 避免退化为实现，除非被明确要求

有用的证据来源包括：

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

推荐的 worker 返回结构：

• Lane
• Hypothesis
• Evidence For
• Evidence Against / Gaps
• Evidence Strength
• Critical Unknown
• Best Discriminating Probe
• Confidence

主导者综合契约

最终 /trace 答案应综合，而非只是拼接。

返回：

• Observed Result
• Ranked Hypotheses
• Evidence Summary by Hypothesis
• Evidence Against / Missing Evidence
• Rebuttal Round
• Convergence / Separation Notes
• Most Likely Explanation
• Critical Unknown
• Recommended Discriminating Probe
• Additional Trace Lanes（可选，仅在不确定性仍然很高时）

即使某个解释当前占主导，也应保留排序后的候选清单。

反驳轮与汇聚检测

在结束追踪前：

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

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

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

显式降级指导

主导者应明确说明某个假设为何被降级：

• 被更强证据反驳
• 缺少它所预测的观察
• 需要额外的特设假设
• 比领先者解释更少的事实
• 在反驳轮中落败
• 汇聚进更强的父解释

这一点很重要，因为 /trace 应教会读者为何某个解释排名高于另一个，而不仅是呈现最终表格。

建议的主导者提示骨架

使用类似以下的团队导向编排提示：

• “精确重述观察。”
• “生成 3 个刻意不同的假设。”
• “使用 Claude 内置团队模式为每个假设创建一条 tracer 通道。”
• “对每条通道，收集支持与反对证据，排序证据强度，并命名关键未知与最佳区分性探测。”
• “如有用，对领先者应用系统、事前分析与科学视角。”
• “在排名前两位的解释之间进行一轮反驳。”
• “返回排序后的解释表、汇聚说明、关键未知，以及单一最佳区分性探测。”

输出质量门槛

良好的 /trace 输出应：

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

示例最终综合形态

Observed Result

[发生了什么]

Ranked Hypotheses

Rank | Hypothesis | Confidence | Evidence Strength | Why it leads 1 | ... | High / Medium / Low | Strong / Moderate / Weak | ...

Evidence Summary by Hypothesis

Hypothesis 1: ... Hypothesis 2: ... Hypothesis 3: ...

Evidence Against / Missing Evidence

Hypothesis 1: ... Hypothesis 2: ... Hypothesis 3: ...

Rebuttal Round

Best rebuttal to leader: ... Why leader held / failed: ...

Convergence / Separation Notes

...

Most Likely Explanation

[当前最佳解释]

Critical Unknown

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

Recommended Discriminating Probe

[单一下一步探测]

Additional Trace Lanes

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