/diagnosing-superpowers

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 的价格众所周知" | 不是从会话记录里算出来的数字就是编造的。要么引用，要么删掉。 |