swing-trace

推理追踪器

反黑箱引擎，让推理链条变得可见、可审计、可拆解。

旨在解决黑箱推理这一认知失效模式——Claude 给出答案，但用户无法看到依据了哪些假设、排除了哪些替代方案，也不知道推理中哪一部分最薄弱。

规则（绝对要求）

1. 绝不呈现单一路径叙述。 每条追踪都必须在有意义的决策分岔处展示至少一个被排除的替代方案。“我考虑过 X，但因为 Z 选择了 Y”是最低要求；最好展示两个被排除的替代方案。
2. 置信度分解必须包含 3 个以上子项。 总体置信度必须分解为至少三个相互独立的维度，每个维度都要有自己的百分比和理由。
3. 每项假设都必须评级。 每项假设都必须明确标注关键性评级（高／中／低）和可验证性评级（可直接验证／可间接验证／不可验证）。不得遗漏评级。
4. 必须提供最薄弱环节。 绝不可跳过。这是价值最高的部分——它会准确告诉用户应重点验证哪里。
5. 禁止虚假的置信度表演。 没有具体理由，不得给出高置信度（>80%）。禁止含糊地诉诸“经验”或“常识”。每个置信度级别都必须引用具体依据。
6. 区分证据类型。 将经验性证据（基准测试、数据、测试结果）与理论推理（设计原则、启发式方法）和权威依据（文档、专家共识）分开。标明每项主张由哪种类型的证据支持。
7. 追踪必须可证伪。 每个结论都必须说明在什么条件下会出错。如果无法说明什么情况能推翻结论，说明推理不够严谨。

模式选择

快速模式（默认）

未使用 --full 调用时，仅执行以下步骤：

1. 阶段 1：主张拆分 — 拆分为原子主张
2. 阶段 2：假设清单 — 列出假设，并标注关键性／可验证性
3. 阶段 5：最薄弱环节与替代结论 — 找出最脆弱的一项假设

跳过阶段 3（决策树）和阶段 4（置信度分解）。

快速模式输出格式：

## Reasoning Trace: [Claim]

### Atomic Claims
1. [Claim 1]
2. [Claim 2]

### Assumption Inventory
| # | Assumption | Criticality | Verifiability |
|---|-----------|-------------|---------------|
| A1 | ... | High/Med/Low | Direct/Indirect/Unverifiable |

### Weakest Link
**Assumption [A#]:** [restate]
- **Why weakest:** [explanation]
- **If wrong:** [alternative conclusion]
- **How to verify:** [concrete steps]

完整模式（--full）

使用 --full 调用时，执行下文所述的全部 5 个阶段。

流程

按顺序执行以下 5 个阶段。不得跳过任何阶段。

阶段 1：主张拆分

确定要追踪的确切主张。将复合问题拆分为原子主张。

Input: "Why did you recommend microservices over a monolith?"
Atomic claims:
  1. Microservices are a better architectural fit for this project
  2. The team can handle microservices operational complexity
  3. The migration cost is justified by long-term benefits

每个原子主张都有自己的假设清单和置信度评分。

阶段 2：假设清单

针对每个原子主张，列出推理所依赖的每一项假设。每项假设包含三个属性：

#	假设	关键性	可验证性
A1	[Statement]	高——若错误，结论会改变	可直接验证——可以测试／测量
A2	[Statement]	中——若错误，结论会减弱	可间接验证——可以从代理数据中推断
A3	[Statement]	低——若错误，结论仍然成立	不可验证——必须依据判断接受或拒绝

关键性量表：

• 高： 如果这项假设错误，结论会反转或变得无法成立。
• 中： 如果错误，结论会显著减弱，但加上限定条件后仍可能成立。
• 低： 如果错误，结论基本不受影响。

可验证性量表：

• 可直接验证： 可以通过测试、测量或权威来源进行确认。
• 可间接验证： 可以从相关数据、基准测试或类比中推断。
• 不可验证： 需要判断或预测，或取决于未来的未知因素。

阶段 3：附带分支理由的决策树

在推理过程中每个重要的分岔点，都要记录：

1. 决策点： 需要回答什么问题？
2. 考虑的选项： 至少 2 个（选中的路径 + 至少 1 个被否决的备选方案）。
3. 评估标准： 哪些因素决定了选择？
4. 选定的路径： 选择了哪个选项？
5. 否决理由： 为什么否决每个备选方案——要说明具体原因，不能含糊其辞。
6. 反转条件： 要满足什么条件，被否决的备选方案才会成为更好的选择？

Decision Point: Database selection
  ├─ Option A: PostgreSQL [CHOSEN]
  │   Strengths: ACID compliance, JSON support, ecosystem maturity
  │   Evidence type: Empirical (benchmarks) + Authority (industry adoption data)
  │
  ├─ Option B: SQLite [REJECTED]
  │   Strengths: Zero-config, embedded, fast for reads
  │   Rejection: Write concurrency limit (~5 writers) incompatible with
  │              multi-instance deployment requirement (Assumption A2)
  │   Reversal: If deployment is single-instance AND write volume < 100/sec,
  │             SQLite becomes the simpler, better choice
  │
  └─ Option C: MongoDB [REJECTED]
      Strengths: Schema flexibility, horizontal scaling
      Rejection: Data has strong relational structure (7 FK relationships);
                 denormalization cost outweighs flexibility benefit
      Reversal: If schema changes weekly or data is primarily document-shaped

阶段 4：信心度拆解

将整体信心度拆解为相互独立的子项。至少 3 项，建议 4–6 项。

每个子项都要提供：

• 一个百分比（0–100%）
• 支持该项的证据类型（实证 / 理论 / 权威来源 / 混合）
• 1–2 句理由，并注明具体依据

整体信心度不是这些子项的平均值。应根据各子项对结论的重要性进行加权。

Overall Confidence: 72%

Sub-components:
  Technical Feasibility:   90% [Empirical] -- proven in similar systems (refs: X, Y benchmarks)
  Timeline Estimate:       45% [Theoretical] -- based on analogy to past project, but team composition differs
  Cost Projection:         60% [Mixed] -- infrastructure costs are empirical, opportunity cost is estimated
  Team Capability Match:   75% [Authority] -- based on stated team skills; not independently verified
  Risk Assessment:         80% [Theoretical] -- standard failure modes well-understood; novel integration untested

Weighted Overall: (90*0.3 + 45*0.25 + 60*0.15 + 75*0.15 + 80*0.15) = 71.5% ≈ 72%

阶段 5：最薄弱环节与替代结论

识别最薄弱环节： 哪一个假设或子结论如果不成立，会对最终答案造成最大影响？

选择最薄弱环节的标准：

1. 在各项假设中关键性最高
2. 最难验证
3. 子项信心度最低
4. 这三个因素的交集就是最薄弱环节

替代结论： “如果[最薄弱环节所依据的假设]不成立，那么结论就会变为[X]。”

这不是空洞的假设性补充，而必须是一个经过充分推理、能够从否定最薄弱假设逻辑推导出的替代结论。

输出格式

## Reasoning Trace: [Claim/Question]

### Atomic Claims
1. [Claim 1]
2. [Claim 2]
3. [Claim N]

### Assumption Inventory
| # | Assumption | Criticality | Verifiability | Tied to Claim |
|---|-----------|-------------|---------------|---------------|
| A1 | [Statement] | High | Directly Verifiable | Claim 1 |
| A2 | [Statement] | High | Unverifiable | Claim 2 |
| A3 | [Statement] | Medium | Indirectly Verifiable | Claim 1, 3 |
| ... | ... | ... | ... | ... |

### Decision Forks

#### Fork 1: [Decision Point]
- **Chosen:** [Option] -- [rationale with evidence type label]
- **Rejected:** [Option] -- [specific rejection reason]
  - *Reversal condition:* [what would make this the right choice]
- **Rejected:** [Option] -- [specific rejection reason]
  - *Reversal condition:* [what would make this the right choice]

#### Fork 2: [Decision Point]
...

### Confidence Decomposition
| Dimension | Confidence | Evidence Type | Basis |
|-----------|-----------|---------------|-------|
| [Dimension 1] | XX% | Empirical | [specific justification] |
| [Dimension 2] | XX% | Theoretical | [specific justification] |
| [Dimension 3] | XX% | Authority | [specific justification] |
| [Dimension N] | XX% | Mixed | [specific justification] |

**Overall Confidence: XX%** (weighted by dimension importance)

### Weakest Link
**Assumption [A#]:** [restate the assumption]
- **Criticality:** High
- **Verifiability:** [rating]
- **Current confidence in this assumption:** XX%
- **Why this is the weakest link:** [explanation]
- **How to verify:** [concrete steps the user can take]

### Alternative Conclusion
> If **[weakest assumption]** is wrong, then:
> [Alternative conclusion with reasoning -- not a throwaway sentence but a genuinely traced alternative]

### Falsification Conditions
The main conclusion is wrong if ANY of these turn out to be true:
1. [Condition 1]
2. [Condition 2]
3. [Condition N]

质量校准

错误示例（不要这样写）

Q: "Why did you recommend React over Vue?"

I recommended React because it has a larger ecosystem, more job
postings, and better TypeScript support. It's the safer choice
for most teams because it's battle-tested at scale by Meta and
many other companies.

Confidence: High.

问题：

• 没有说明假设——所谓“高度确信”是基于什么？
• 没有探讨备选方案——是否认真考虑过 Vue？
• 没有指出最薄弱环节——用户应该质疑什么？
• 没有展示决策分岔点——选择“更大”或“更好”的标准是什么？
• “经过大规模实战检验”是没有具体依据的诉诸权威
• 读起来像营销文案，而不是推理过程的记录

正确示例（以此为目标质量）

## Reasoning Trace: Why React over Vue for this project?

### Atomic Claims
1. React is a better framework fit for this project's requirements
2. The team will be more productive with React than Vue
3. React's ecosystem advantage outweighs Vue's simplicity advantage

### Assumption Inventory
| # | Assumption | Criticality | Verifiability | Tied to Claim |
|---|-----------|-------------|---------------|---------------|
| A1 | Team has 2+ engineers with React experience | High | Directly Verifiable | Claim 2 |
| A2 | Project requires complex state management | Medium | Directly Verifiable | Claim 1 |
| A3 | Hiring pipeline will favor React candidates | High | Indirectly Verifiable | Claim 2 |
| A4 | Project will need SSR capabilities | Medium | Directly Verifiable | Claim 1 |
| A5 | TypeScript will be used project-wide | Low | Directly Verifiable | Claim 3 |

### Decision Forks

#### Fork 1: Framework Selection
- **Chosen:** React -- larger component ecosystem (npm: 90k+ packages
  tagged "react" vs 25k+ "vue"), more mature SSR story (Next.js 15 stable
  vs Nuxt 4 recent), team has existing React experience (A1)
- **Rejected:** Vue -- lower learning curve, better developer ergonomics
  for smaller teams, Composition API is excellent
  - *Reversal condition:* If team has 0 React experience AND project is
    < 6 month lifespan AND no SSR needed, Vue's faster onboarding wins
- **Rejected:** Svelte -- best DX, smallest bundle, genuinely better
  reactivity model
  - *Reversal condition:* If team is greenfield (no framework experience),
    project is performance-critical consumer app, and hiring is not a
    constraint (small, stable team)

### Confidence Decomposition
| Dimension | Confidence | Evidence Type | Basis |
|-----------|-----------|---------------|-------|
| Framework capability match | 85% | Empirical | Feature comparison against requirements doc |
| Team productivity | 55% | Mixed | Based on stated skills (A1); not observed |
| Ecosystem longevity | 80% | Authority | Meta backing, npm download trends, State of JS 2025 |
| Hiring advantage | 50% | Indirectly Empirical | LinkedIn job postings (3:1 React:Vue ratio, but market shifts) |

**Overall Confidence: 68%** (productivity and hiring are uncertain
but heavily weighted)

### Weakest Link
**Assumption A1:** Team has 2+ engineers with React experience
- **Criticality:** High
- **Verifiability:** Directly Verifiable
- **Current confidence:** 70% (stated by PM, not verified via code review)
- **Why this is the weakest link:** If the team lacks real React
  experience, the productivity advantage evaporates and Vue's lower
  learning curve becomes the dominant factor
- **How to verify:** Review team members' recent commits; conduct
  brief technical screen on React patterns (hooks, context, suspense)

### Alternative Conclusion
> If **team React experience (A1)** is overstated, then Vue is the
> better choice: its gentler learning curve (Composition API maps
> well to React hooks mental model but with less boilerplate),
> better documentation, and faster time-to-productive offset the
> smaller ecosystem. The recommendation flips to Vue with Nuxt.

### Falsification Conditions
1. Team has < 2 engineers genuinely proficient in React (not just "used it once")
2. Project scope shrinks to < 6 months with no SSR requirement
3. Hiring is not a concern (stable team, no growth planned)

适用场景

• 给出任何建议之后：“为什么选 Postgres？”“为什么用微服务？”“为什么选这个库？”
• 给出任何估算之后：“为什么要 2 周？”“为什么要 50k 美元？”“为什么需要 3 名工程师？”
• 需要利益相关方审查推理过程的架构决策
• 代码评审的理由：“为什么你把这标记为安全问题？”
• 用户说“说服我”或“我不太确定”
• 事后分析：“我们当时为什么认为 X 会奏效？”
• 任何必须经得起审查的高风险决策

不适用场景

• 答案明确的简单事实查询（“Postgres 使用什么端口？”）
• 结构化推理会扼杀创意的头脑风暴（使用 swing-options）
• 用户明确表示想要快速答复时
• 没有具体论断需要追溯的全面代码／系统分析
• 对他人的推理进行压力测试（使用 swing-review——它会进行攻击；本技能则是揭示推理）
• 需要外部来源核实的研究（事实查询使用 swing-research；本技能用于追溯对事实的推理）

注意事项

1. 快速模式是默认模式。 除非指定 --full，否则只运行阶段 1、2 和 5。快速模式下不要生成决策树或置信度分解——这会浪费上下文。
2. 未经具体证据佐证，置信度绝不能超过 80%。“常识”“广为人知”“普遍认可”都不能作为依据。请指出基准测试、文档或测试结果。
3. 所有模式都必须包含最薄弱环节。 快速模式也不例外。这是价值最高的单项输出——如果跳过它，整个推理记录就毫无意义。
4. 为每项假设评级。 缺少关键性和可验证性评级的假设是不完整的。没有例外，也不能以“显而易见”为由跳过评级。
5. 替代结论必须经过真正的推理。“如果 X 错了，就重新考虑”是废话。请追溯实际的替代逻辑：“如果 X 错了，那么 Y 就成立，因为 Z。”

集成说明

• 与 swing-clarify 配合： 调用此技能之前，先对有歧义的请求运行 swing-clarify。明确范围能带来更好的结果。
• 在 swing-review 之前： 先追溯推理过程，再对其进行压力测试。swing-trace 的假设清单会直接为 swing-review 提供攻击向量。
• 在 swing-research 之后： 研究会收集已核实的事实；随后，swing-trace 会让连接这些事实与结论的逻辑过程清晰透明。
• 与 swing-options 配合： swing-options 生成选项后，swing-trace 可以追溯为何选择某个选项而非其他选项。