Diagnosing Superpowers Skill

Diagnosing Superpowers 是 v6.4.1 新增的診斷型 skill，用來回答一個過去只能憑印象猜的問題：**「這個 session 的 superpowers 到底哪裡出了問題？」」

何時使用

✅ 必須使用的情境：

• session 重複做同樣的工作（一個任務做了三遍）
• 計畫被無視——agent 明明有一份 plan 卻自己亂做
• 某個 skill 應該觸發卻沒有觸發
• 帳單金額異常，想知道 token 燒在哪裡
• 想知道某次「不順」的 session 是流程問題還是模型問題

❌ 不適合的情境：

• 程式碼本身有 bug（應使用 systematic-debugging——那是診斷程式，這是診斷 agent session）
• session 還在順利進行中（沒有問題就不用診斷）

觸發方式

直接用自然語言對 agent 說：

「figure out what went wrong with superpowers in this session」
（診斷這個 session 的 superpowers 哪裡出了問題）

支援當前 session 或過去的 session——出問題的 session 已經結束也來得及診斷。

工作流程

第 1 步：Pin down 問題

skill 會先與你一起把問題 pin down（釐清）：症狀是什麼、什麼時候開始、預期與實際的差異。先定義問題，不是立刻下結論。

第 2 步：讀 transcripts

接著它去讀磁碟上的 transcripts（session 逐字記錄）。

這是整個 skill 的核心設計：session 時間一長，模型對「剛剛發生了什麼」的敘述並不可靠；transcript 才是 ground truth（事實來源）。診斷的證據基礎是外部持久化的記錄，不是模型的內省。

第 3 步：附證據回報

每個發現（finding）都附 path:line 證據——指向 transcript（或相關檔案）的確切位置，你可以自己驗證，不必信任 agent 的轉述。

第 4 步（視要求）：打包或草擬 issue

• Scrubbed bundle：建立去除敏感內容的封存包，適合分享或求助
• 草擬 GitHub issue：幫你寫好 issue 草稿——先給你核准，引用的證據原樣保留，不會被 scrub 到失去線索

實際範例

使用者輸入：

上一個 session 我明明核准了 plan，agent 卻好像沒在照做，
請診斷那個 session 的 superpowers 哪裡出了問題。

可能的診斷輸出（示意）：

## 發現 1：計畫在 ledger 中從未被標記為已讀
證據：.superpowers/sdd/<plan>/ledger.md:3
→ controller 在 setup 階段讀了 plan 檔，但 ledger
  首行未記錄計畫名稱，後續 resume 時視為無計畫狀態。

## 發現 2：skill 觸發被覆蓋
證據：transcript.jsonl:1847
→ 使用者在 t=14:32 的訊息含「不用跑測試」，
  觸發了 verification skip 分支。

與 systematic-debugging 的分界

學習重點

這個 skill 示範了自省（introspection）的正確做法：讓 agent 讀自己的 transcripts 找根因，而不是問它「你覺得你剛剛為什麼這樣做」。自我診斷的可靠度取決於證據基礎——外部持久化的記錄永遠優於模型的自我感受。這個原則同樣適用於任何需要「事後還原決策過程」的系統設計。

本 skill 於 v6.4.1（#2236、#2287）引入。同版原先預定的 proving-it-works-with-a-movie skill 延後至後續版本。