---
name: diagnosing-superpowers
description: 当一次 superpowers 会话出了问题、你的人类伙伴想知道原因时使用——重复劳动、无视计划、磕磕绊绊、结果质量差、某个技能没触发、"太慢了"、"为什么这么贵"、"它到底在干什么"——或者想给 superpowers 维护者整理一份 bug 报告；适用于当前会话，或按 id / 路径指定的过往会话，任何工具均可
version: "1.0.0"
license: MIT
metadata:
  hermes:
    tags: [debugging, diagnosis]
---

# 诊断 Superpowers

## 概述

和你的人类伙伴一起明确一次会话到底哪里出了问题，读取磁盘上的会话记录（transcript），
用证据报告发生了什么。你负责报告，不负责诊断 superpowers。superpowers 要不要改，
由分诊这份打包材料或这条 issue 的人决定。

**核心原则：** 每条发现都要引用 `path:line`。没有引用，就不算发现。每个数字都来自
会话记录或你亲自跑过的命令，绝不凭记忆。

## 工作流

每一步建一个待办。第 5–7 步只在各自注明的条件下执行。

1. **问题受理。** 一次只问一个问题，直到你能写出一段陈述：点名是哪个（些）会话、
   已知的话给出轮次范围、你的伙伴期望什么、实际发生了什么、他们关心的可观测量
   （耗时、token、重复动作、某一个具体动作）。"太慢了"是抱怨，不是问题陈述。
   记下目标是否是一份 superpowers bug 报告。
2. **定位。** 按 `references/session-discovery.md` 把每个会话解析成经过核实的
   绝对文件系统路径。确认过往会话时，引用它的第一条提示词和时间戳，并列出你排除的
   每个候选及理由，没有就写"none"。枚举子智能体的会话记录。创建
   `~/.superpowers/diagnosing-superpowers/<session-id>/`，把路径告诉你的伙伴，
   在其中填写 `templates/case.md`，环境与技能观察遵循其中的来源标注规则。
3. **分诊。** 先亲自读报告问题附近的那一段。然后为每个维度并行派发一个分析员子智能体，
   每个都给它：案例文件路径、`prompts/analyst-common.md`，以及 `prompts/` 下的一个
   维度文件：`skill-timeline.md`、
   `plan-adherence.md`、`repeated-work.md`、`stumbles.md`、
   `quality-evidence.md`、`request-conflicts.md`、`cost-and-time.md`。
   会话记录很长时，按轮次范围拆分一个维度。凡是返回的发现没有 `path:line`，一律丢弃。
4. **报告。** 按顺序填写 `templates/report.md` 的每一节，写入工作区，展示出来，
   并给出路径。核对被引用的内容实际能证明什么，并保留支撑它的案例；符号链接别名
   不算冗余副本。
5. **GitHub issue** —— 当报告 §7 写的是 possible 或 likely，或你的伙伴要求时。
   按 `references/github-issues.md` 在已开放和已关闭的 issue 中搜索这些症状。
   展示匹配结果，建议把报告补充到最接近的那条。如果都不匹配，填写
   `templates/issue.md`，写入工作区，展示确切文本，获得批准后才创建 issue。
   `gh` 不能附加文件；如果有打包材料，把路径给你的伙伴，让他们在浏览器里附上。
6. **导出** —— 只在你的伙伴要求打包时进行；绝不主动打包。如果受理时的目标是 bug
   报告，说一次"可以按需提供脱敏后的打包材料"，然后等待。询问脱敏级别，并说明每一级
   包含什么：skeleton（不含工具结果正文）、evidence（只含被引用事件的正文）、full。
   按 `templates/bundle-README.md` 构建打包材料，派发 `prompts/scrub.md`，再派发
   `prompts/scrub-audit.md`，两者反复执行，直到审计返回 CLEAN。
   先完成打包模板里的证据核对与对账，再展示最终的脱敏日志、文件清单，以及隐私与
   证据两方面的结论。获得批准后才归档（`zip -r` 或 `tar -czf`）。给出归档路径时，
   说明其中包含什么，指向脱敏日志查看替换情况，并说明脱敏可能有遗漏：他们必须在
   分享前逐个审阅每个文件。
7. **相似会话** —— 被要求时进行。把已确认的发现转成一个特征签名，按修改时间和大小
   列出候选，找到标记所在的行号，对每个候选并行派发 `prompts/similar-session.md`，
   然后追加到报告 §9。

## 速查

七个分析员始终全部运行。这张表说明第 3 步里你自己先读哪一段，以及结论中先讲哪些发现。

| 抱怨 | 先读、先讲 |
|---|---|
| "太慢了" | cost-and-time、stumbles |
| "它为什么做了额外的活？" | repeated-work、plan-adherence |
| "为什么这么贵？" | cost-and-time |
| "它到底在干什么？"（仍在运行） | skill-timeline；在覆盖说明中注明仍在进行 |
| "它无视了计划" | plan-adherence，先看压缩（compaction）所在行 |
| "技能 X 从没触发" | skill-timeline |

## 硬性规则

- **上下文安全。** 一行会话记录就可能有一兆字节。每个会话文件、每一次，都要遵循
  `references/context-safety.md`。
- **只读。** 绝不修改、移动或删除会话文件。
- **给子智能体确切路径。** 子智能体的"当前会话"是它自己的会话。传绝对路径和 id。
- **只认人类提示词。** hook 输出、system reminder 和工具结果都不是你伙伴说的话。
  在子智能体的会话记录里，"user" 是父智能体。
- **不诊断 superpowers。** 报告 §7 只陈述是否涉及，到此为止。绝不指出某个技能的缺陷，
  也不提议修改。你的伙伴催着要修复，也不能豁免这一条；指向 issue 那一步，并提一句
  可以按需提供打包材料。也不要给你的伙伴提建议。
- **批准关卡。** 你的伙伴看过脱敏日志和文件清单之前，不归档。他们批准确切文本之前，
  不发 issue 或评论。
- **先受理，后分析。** 你的伙伴答复之前，第 2–7 步一律不开始。如果他们不在，写下问题
  然后停下。你替他们重构出来的陈述不算答复。一个范围已经明确的请求——某个具体事件、
  现在正在运行什么、或者要跑哪项分析——本身就是陈述：先回答它，再提问。
  针对整个会话的"为什么"是抱怨。

## 危险信号

| 想法 | 现实 |
|---------|---------|
| "问题很明显，跳过受理" | 问题陈述决定了一切的范围。去问。 |
| "他们不在，那我来重构陈述" | 你无法重构他们想要什么。写下问题，然后停下。 |
| "我先全部扫一遍，最后再问" | 无范围的扫描会把他们的预算花在错误的问题上。先问。 |
| "他们要 bug 报告，那我现在就打包" | 打包材料就是他们打包起来的会话数据。只在他们要求时才构建。 |
| "只是个小的定点修改，不用重构" | 再小也不归你决定。报告证据；由分诊的人决定。 |
| "每个 token 的价格众所周知" | 不是从会话记录里算出来的数字就是编造的。要么引用，要么删掉。 |