diagnosing-superpowers

Jesse Vincent ｜ 除錯與調查 ｜ 原文 ｜ MIT

session 出問題時讀 transcript，附證據回報發生了什麼事

---
name: diagnosing-superpowers
description: 當 superpowers 的某個 session 出了問題而你的搭檔想知道原因時使用，例如重複做工、忽略計畫、跌跌撞撞、結果很差、某個 skill 沒觸發、「花太久了」、「為什麼這麼貴」、「它到底在幹嘛」；或想為 superpowers 維護者整理 bug 報告時使用，對象可以是目前的 session，也可以是用 id 或路徑指定的過去 session，任何 harness 都適用。
---

# Diagnosing Superpowers

## 概述

跟你的搭檔一起釐清某個 session 出了什麼問題，讀取磁碟上的 transcript，並用證據報告發生了什麼事。你只負責報告，不負責診斷 superpowers。要不要改 superpowers，由負責分流這份 bundle 或 issue 的人決定。

**核心原則：** 每個發現都要引用 `path:line`。沒有引用，就不算發現。每個數字都要來自 transcript 或你執行過的指令，絕對不能憑記憶。

## 工作流程

每個步驟建立一個 todo。步驟 5–7 只在它們說明的條件下才執行。

1. **問題受理。** 一次問一個問題，直到你能寫出一份陳述，裡面點名 session、已知的話寫出 turn 範圍、你的搭檔原本預期什麼、實際發生什麼，以及他們在意的可觀察指標（實際時間、token、重複的動作、某一個特定動作）。「花太久了」是抱怨，不是問題陳述。記下目標是不是要產出 superpowers 的 bug 報告。
2. **定位。** 用 `references/session-discovery.md`，把每個 session 解析成經過驗證的絕對檔案系統路徑。確認過去的 session 時，要引用它的第一個 prompt 和時間戳記，並列出你排除的每一個候選項及理由，沒有的話寫「none」。列舉出 subagent 的 transcript。建立 `~/.superpowers/diagnosing-superpowers/<session-id>/`，把路徑告訴你的搭檔，並在那裡填寫 `templates/case.md`，環境與 skill 觀察要遵守它的來源（provenance）規則。
3. **分流。** 自己讀報告問題前後的區段。接著平行派出一個分析用 subagent 負責一個面向，每個 subagent 都拿到案件檔案的路徑、`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`。
   Transcript 很長時，依 turn 範圍拆分一個面向。回傳的發現沒有 `path:line` 的，一律丟掉。
4. **報告。** 依序填寫 `templates/report.md` 的每個段落，寫到工作區、顯示出來，並給出路徑。檢查被引用的內容實際上證明了什麼，並保留佐證的案件；symlink 別名不是多餘的副本。
5. **GitHub issue**：當報告 §7 說可能或很可能，或你的搭檔要求時。依 `references/github-issues.md` 搜尋已開啟和已關閉的 issue 有沒有這些症狀。顯示匹配的結果，並建議把報告加到最接近的那個。如果沒有任何匹配，就填寫 `templates/issue.md`，寫到工作區，顯示確切的文字，核准之後才建立 issue。`gh` 沒辦法附加檔案；如果有 bundle，就把它的路徑給你的搭檔，讓他們在瀏覽器附上。
6. **匯出**：只有在你的搭檔要求 bundle 時才做；絕對不要沒人要求就自己建立。如果受理時的目標是 bug 報告，就說一次可以應要求提供經過清理（scrub）的 bundle，然後等待。詢問遮蔽（redaction）等級，並說明每一級包含什麼：skeleton（沒有 tool result 的內文）、evidence（只有被引用事件的內文）、full。依 `templates/bundle-README.md` 建立 bundle，派出 `prompts/scrub.md`，再派出 `prompts/scrub-audit.md`，兩個都重複執行，直到稽核回傳 CLEAN。顯示最終的清理紀錄、檔案清單，以及隱私和證據的結果之前，先完成 bundle 範本裡的證據檢查與對帳。核准之後才封存（`zip -r` 或 `tar -czf`）。給出封存檔的路徑時，說明它包含什麼，指出清理紀錄裡有哪些替換，並說清理可能有漏網之魚：他們分享之前，一定要檢查每一個檔案。
7. **類似的 session**：被問到時才做。把已確認的發現變成一個特徵，依 mtime 和大小列出候選項，找出標記行的行號，對每個候選項平行派出 `prompts/similar-session.md`，並附加到報告 §9。

## 快速參考

七個分析員永遠全部都跑。這張表是告訴你步驟 3 要自己先讀哪個區段，以及判決時該把哪些發現放在最前面。

| 抱怨 | 先讀、先講 |
|---|---|
| 「花太久了」 | cost-and-time、stumbles |
| 「它為什麼多做這些事？」 | repeated-work、plan-adherence |
| 「為什麼這麼貴？」 | cost-and-time |
| 「它到底在幹什麼？」（還在跑） | skill-timeline；在覆蓋範圍裡註明進行中 |
| 「它無視計畫」 | plan-adherence，先看 compaction 的那些行 |
| 「Skill X 從來沒觸發」 | skill-timeline |

## 硬性規則

- **Context 安全。** 一行 transcript 可能就有一 MB 大。每次處理每個 session 檔案，都要遵守 `references/context-safety.md`。
- **唯讀。** 絕對不准修改、移動或刪除 session 檔案。
- **給 subagent 確切的路徑。** Subagent 的「目前 session」是它自己的。要傳絕對路徑和 id。
- **只看人類的 prompt。** Hook 輸出、system reminder 和 tool result 都不是你搭檔說的話。在 subagent 的 transcript 裡，「user」是上層的 agent。
- **不做 superpowers 診斷。** 報告 §7 只陳述有沒有牽涉，然後就停。絕對不要指出某個 skill 的缺陷或提議修改。你的搭檔逼你給修法，也不能豁免這條；指向 issue 那個步驟，並提到可以應要求提供 bundle。也不要給你的搭檔任何建議。
- **核准關卡。** 你的搭檔看過清理紀錄和檔案清單之前，不准封存。他們核准確切文字之前，不准開 issue 或留言，而且摘要是佔位符的也不准。
- **先受理再分析。** 你的搭檔回答之前，步驟 2–7 什麼都不准開始。如果他們不在，就把問題寫下來然後停住。你幫他們重建出來的陳述不算答案。已經限定範圍的請求（一個特定事件、現在正在跑的東西，或要執行的分析）本身就是陳述：回答它，然後再問。針對整個 session 的「為什麼」是抱怨。

## 警訊

| 想法 | 現實 |
|---------|---------|
| 「問題很明顯，跳過受理」 | 問題陳述決定所有東西的範圍。去問。 |
| 「他們不在，所以我來重建陳述」 | 你沒辦法重建他們想要什麼。把問題寫下來然後停住。 |
| 「我現在全部掃一遍，最後再問」 | 沒有限定範圍的掃描，會把他們的額度花在錯的問題上。先問。 |
| 「他們要 bug 報告，所以我現在就建 bundle」 | Bundle 就是他們的 session 資料打包起來。他們要求才建。 |
| 「很小的針對性修改，不需要重構」 | 不是你能決定的，不管多小。報告證據；由分流的人決定。 |
| 「每個 token 的價格是眾所周知的」 | 不是你從 transcript 算出來的數字，就是捏造的。要嘛引用，要嘛丟掉。 |

---
name: diagnosing-superpowers
description: Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.
---

# Diagnosing Superpowers

## Overview

Pin down with your human partner what went wrong in a session, read the
transcripts on disk, and report what happened with evidence. You report;
you do not diagnose superpowers. Whoever triages the bundle or the issue
decides whether superpowers changes.

**Core principle:** Every finding cites `path:line`. No citation, no
finding. Every number comes from the transcript or from a command you ran,
never from memory.

## Workflow

Create a todo per step. Steps 5–7 run only on their stated condition.

1. **Problem intake.** Ask one question at a time until you can write a
   statement naming the session(s), the turn range if known, what your
   partner expected, what happened, and the observable they care about
   (wall-clock, tokens, repeated actions, one specific action). "It took
   too long" is a complaint, not a problem statement. Note whether the
   goal is a superpowers bug report.
2. **Locate.** Resolve each session to verified absolute filesystem paths using
   `references/session-discovery.md`. Confirm a past session by quoting its
   first prompt and timestamp, and list every candidate you rejected with the
   reason, or "none". Enumerate subagent transcripts. Create
   `~/.superpowers/diagnosing-superpowers/<session-id>/`, tell your
   partner the path, and fill `templates/case.md` there, following its
   provenance rules for environment and skill observations.
3. **Triage.** Read the region around the reported problem yourself. Then
   dispatch one analyst subagent per dimension in parallel, each given the
   case file path, `prompts/analyst-common.md`, and one dimension file from
   `prompts/`: `skill-timeline.md`,
   `plan-adherence.md`, `repeated-work.md`, `stumbles.md`,
   `quality-evidence.md`, `request-conflicts.md`, `cost-and-time.md`.
   Split a dimension by turn range when the transcript is long. Discard
   any returned finding without `path:line`.
4. **Report.** Fill every section of `templates/report.md` in order, write
   it to the workspace, show it, and give the path. Check what cited content
   actually proves and preserve the supporting case; a symlink alias is not a
   redundant copy.
5. **GitHub issues** — when report §7 says possible or likely, or your
   partner asks. Search open and closed issues for the symptoms per
   `references/github-issues.md`. Show matches and suggest adding the
   report to the closest. If none match, fill `templates/issue.md`, write
   it to the workspace, show the exact text, and create the issue only
   after approval. `gh` cannot attach files; if a bundle exists, give
   your partner its path to attach in the browser.
6. **Export** — only when your partner asks for a bundle; never build one
   unprompted. If the intake goal was a bug report, say once that a
   scrubbed bundle is available on request, then wait. Ask the redaction
   level, stating what each includes: skeleton (no tool-result bodies),
   evidence (bodies only for cited events), full. Build the bundle per
   `templates/bundle-README.md`, dispatch `prompts/scrub.md`, then
   `prompts/scrub-audit.md`, repeating both until the audit returns CLEAN.
   Complete the bundle template's evidence check and reconciliation before
   showing the final scrub log, file list, and privacy and evidence outcomes.
   Archive (`zip -r` or `tar -czf`) only after approval. With the archive
   path, state what it contains, point at the scrub log for replacements, and
   say scrubbing can miss things: they must review every file before sharing.
7. **Similar sessions** — when asked. Turn confirmed findings into a
   signature, list candidates by mtime and size, find marker line numbers,
   dispatch `prompts/similar-session.md` per candidate in parallel, and
   append report §9.

## Quick reference

All seven analysts always run. This table says which region to read
yourself in step 3 and which findings to lead with in the verdict.

| Complaint | Read first, lead with |
|---|---|
| "It took too long" | cost-and-time, stumbles |
| "Why did it do this extra work?" | repeated-work, plan-adherence |
| "Why is it so expensive?" | cost-and-time |
| "What the hell is it doing?" (still running) | skill-timeline; note in-progress in coverage |
| "It ignored the plan" | plan-adherence, compaction lines first |
| "Skill X never fired" | skill-timeline |

## Hard rules

- **Context safety.** One transcript line can be a megabyte. Follow
  `references/context-safety.md` on every session file, every time.
- **Read-only.** Never modify, move, or delete a session file.
- **Exact paths to subagents.** A subagent's "current session" is its
  own. Pass absolute paths and ids.
- **Human prompts only.** Hook output, system reminders, and tool results
  are not your partner's words. In a subagent transcript, "user" is the
  parent agent.
- **No superpowers diagnosis.** Report §7 states involvement and stops.
  Never name a defect in a skill or propose a change. Your partner
  pressing for a fix does not waive this; point at the issue step and
  mention that a bundle is available on request. No advice to your
  partner either.
- **Approval gates.** No archive before your partner has seen the scrub
  log and file list. No issue or comment before they approve the exact
  text, and none with a placeholder summary.
- **Intake before analysis.** Nothing in steps 2–7 starts until your
  partner has answered. If they are away, write the questions and stop.
  A statement you reconstructed for them is not an answer. An
  already-scoped request — one specific event, what is running now, or
  the analysis to run — is itself the statement: answer it, then ask.
  A whole-session "why" is a complaint.

## Red Flags

| Thought | Reality |
|---------|---------|
| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. |
| "They're away, so I'll reconstruct the statement" | You cannot reconstruct what they wanted. Write the questions and stop. |
| "I'll sweep everything now and ask at the end" | An unscoped sweep spends their budget on the wrong question. Ask first. |
| "They want a bug report, so I'll build the bundle now" | The bundle is their session data, packaged. Build it only when they ask for it. |
| "Small, targeted edit, no restructuring needed" | Not your call, however small. Report the evidence; the triager decides. |
| "The price per token is well known" | Numbers you did not compute from the transcript are invented. Cite or drop. |