superpowers-mcp 6.3.9 → 6.4.1

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![版本](https://img.shields.io/badge/version-6.3.9-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.4.1-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將 Superpowers 技能庫與自主 Agent 工作流架構打包成獨立、高效能且安全加固的 **Model Context Protocol (MCP)** 伺服器之相關資訊與使用說明。
@@ -23,7 +23,7 @@
 | :--- | :--- | :--- |
 | **Tools (工具)** | `list_skills`, `read_skill` | 依需求隨時探索、搜尋並載入技能完整內容與操作規範。 |
 | **Prompts (提示詞)** | 9 個原生 Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
-| **Resources (資源)** | 14 項技能 URI + 1 項指南 | `skill://superpowers/<skill-name>`，以及 `guide://superpowers/skill-compositions` |
+| **Resources (資源)** | 15 項技能 URI + 1 項指南 | `skill://superpowers/<skill-name>`，以及 `guide://superpowers/skill-compositions` |
 
 ### 與 AI Agent 對話（基礎操作）
 
@@ -154,15 +154,15 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ---
 
-## 📋 支援技能總覽 (14 項核心技能與適用情境)
+## 📋 支援技能總覽 (15 項核心技能與適用情境)
 
-為了讓您能快速選用合適的技能，我們將 14 個技能依照軟體開發生命週期 (SDLC) 進行分類，並整合其核心用途與社群推薦使用情境：
+為了讓您能快速選用合適的技能，我們將 15 個技能依照軟體開發生命週期 (SDLC) 進行分類，並整合其核心用途與社群推薦使用情境：
 
 | # | 開發階段 (Phase) | 技能名稱 (Skill Name) | 它是幹嘛用的？ (Purpose & Core Value) | 推薦使用情境 (Recommended Scenario) |
 | :-: | :--- | :--- | :--- | :--- |
 | 1 | **🚀 規劃與設計** | **`brainstorming`** | **需求澄清與設計探索**：在寫代碼前探索架構方案、釐清邊界，產出 Spec。內建 Visual Companion 瀏覽器即時設計審查。 | 啟動任何新功能或大改版前，防止 AI 直接衝進去寫 code。 |
 | 2 | **🚀 規劃與設計** | **`writing-plans`** | **實作計畫拆解**：將設計規格分解為獨立可測試的原子任務清單，標註檔案契約與 Recommended Skill。 | 進行多檔案重構、複雜遷移或大型開發前，建立清晰藍圖。 |
-| 3 | **💻 開發與實作** | **`executing-plans`** | **會話內計畫執行**：在當前會話中依據計畫逐步批次執行任務，並於關鍵節點進行檢查點審查。 | 不需要開多個 Subagent 時的連續計畫執行。 |
+| 3 | **💻 開發與實作** | **`executing-plans`** | **會話內計畫執行**：在當前會話中依據計畫逐步執行全部任務，完成後再做一次全分支審查。 | 不需要開多個 Subagent 時的連續計畫執行。 |
 | 4 | **💻 開發與實作** | **`subagent-driven-development`** | **子代理驅動開發 (SDD)**：為各任務派發乾淨上下文的獨立 Subagent 實作，並在任務間發起雙層對抗式代碼審查。 | 推薦的複雜計畫執行方式，防止上下文污染並提高精確度。 |
 | 5 | **💻 開發與實作** | **`test-driven-development`** | **測試驅動開發 (TDD)**：嚴格執行「紅燈（寫失敗測試）➔ 綠燈（最小實作）➔ 重構」循環。 | 實作邏輯複雜功能時，確保代碼隨附測試且具備回歸防護。 |
 | 6 | **🔍 除錯與排查** | **`systematic-debugging`** | **系統性除錯與根因分析**：將問題拆解為可測試的假說並設計驗證實驗，徹底杜絕盲猜式亂改。 | 遇到任何報錯、異常行為或難以重現的 Bug 時。 |
@@ -174,10 +174,47 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 | 12 | **🤖 進階調度** | **`dispatching-parallel-agents`** | **並行代理調度**：在隔離環境中同時派發多個 Subagent 平行驗證獨立假說或處理多個子任務。 | 多個測試同時失敗，需要加速並行排查根因時。 |
 | 13 | **🤖 進階調度** | **`using-superpowers`** | **Superpowers 基礎紀律**：MCP 入口技能，引導 Agent 在任何任務前主動搜尋並載入對應技能規範。 | 開啟對話時自動載入，規範 AI 的行為準則。 |
 | 14 | **🤖 進階調度** | **`writing-skills`** | **技能撰寫與維護**：規範如何為團隊建立、測試與封裝新的 Superpowers 技能。 | 需要擴充專屬新技能或更新既有技能時。 |
+| 15 | **🤖 進階調度** | **`diagnosing-superpowers`** | **會話鑑識與錯誤回報**：依據磁碟上的對話紀錄重建出錯原因並附引證；可產出脫敏 bundle 與 GitHub issue 草稿。 | 會話走偏需要證據釐清原因，或要向 Superpowers 維護者回報問題時。 |
 
 ## 🆕 最近更新
 
-### v6.3.9 (最新版)
+### v6.4.1 (最新版)
+
+- **上游同步至 obra/superpowers v6.4.1**：
+  - **原生會話內執行**：重寫的 `executing-plans` 以新版 `task-start` / `task-done` 跑完全部計畫，最後再做一次全分支審查，不再中途停下來確認。
+  - **新技能 `diagnosing-superpowers`**：依據磁碟紀錄做會話鑑識並附引證，可產出脫敏 bundle 與 GitHub issue 草稿（共 15 個技能）。
+  - **審查行為**：以合理使用者期望評斷未載明行為、`Declined to judge` 清單、`BASE_SHA` 改用 `git merge-base origin/main HEAD`。
+  - **計畫 Review Focus**：新增模板章節與自查項，將規格隱含的邊界案例釘到負責的任務。
+  - **新平台參照**：Muse 與 Claude Code 工具對照；Devin / OpenCode 參照保留。
+  - 腳本一律透過直譯器（`bash` / `node`）呼叫，避免市集打包剝除執行位元導致失效。
+- **Windows 對等與迴歸防線**：
+  - 新增 `task-start.ps1` / `task-done.ps1` 與 sh/ps1 對稱測試。
+  - 既有 PR 採用內容全數保留（Discoveries 帳本、審查檔契約、greenfield 腳本、遠端安全邊界）；drift 基準重錄，零殘留差異。
+- **全方位安全審計與回歸測試底線**（[`SECURITY.md`](SECURITY.md)）：
+  - 全套件 **365 項自動化測試斷言**（Node.js: 170、Bash: 67、PowerShell: 128）100% 通過，0 漏洞、0 敏感資訊外洩。
+  - 會話內 `task-done` 以 argv 執行操作者指定的測試（`"$@"` / `& $exe @rest`），不是 shell；帳本內容僅供顯示。
+  - `diagnosing-superpowers` 僅讀本機紀錄、匯出需對方同意；脫敏為盡力而為，分享前仍須人工檢查。
+  - 延後發現匯出已涵蓋 `Final: minor (deferred):`，且不會誤抓完成列的 parked 計數。
+  - 本機 Devin 設定（`.devin/`）已列入 gitignore。
+
+### v6.3.10
+
+- **全域安裝引擎鍵名衝突化解與使用者設定無損保留**：
+  - 自動探索既有的 `servers`、`mcp`、`mcpServers`，防止在不同 AI Client 環境中重複建立互相矛盾的設定區塊。
+  - 重新執行安裝時自動合併並無損保留使用者自訂的 `env`、`cwd`、`disabled`、`alwaysAllow` 等欄位。
+  - 徹底消除 `disabled: true` 與 `enabled: true` 同時並存的矛盾無效狀態。
+  - 嚴格校驗命令列引數，拒絕未預期的位置參數（結束碼 1）；全面以 `process.exitCode` 取代突兀退出，確保非同步串流完整沖刷。
+- **核心技能引擎單次 Stat 快照校驗與世代隔離**：
+  - 引入單次 `fs.stat` 快照校驗 (`dev`, `ino`, `size`, `mtimeMs`)，若符號連結或實體檔案遭置換立即失效快取，無需重新遍歷整個目錄。
+  - `clearCache()` 採用單調遞增的 `scanEpoch` 並重設 `loadingEpoch`，杜絕慢速異步掃描在快取重設後的髒覆寫。
+  - 權威描述元 Inode 校驗 (`readFileNoFollow`) 消除 TOCTOU 描述元置換競態。
+- **MCP Prompt 模板健壯性與去重機制**：
+  - 遇到空白或遺失模板時主動輸出結構化 `stderr` 並拋出標準 `McpError(ErrorCode.InternalError)`。
+  - 以 `appliedInterpolations` 追蹤已替換標記，防止多餘參數重複追加。
+- **全方位安全審計與回歸測試底線**：
+  - 全套件 **292 項自動化測試斷言**（Node.js: 163 項、Bash: 35 項、PowerShell: 94 項）100% 通過，0 漏洞、0 敏感資訊外洩。
+
+### v6.3.9
 
 - **永久 ReDoS 防禦（CodeQL Alert #4 關閉）**：
   - 將 YAML 解析（`updateYamlConfig`）中的多項式回溯正則改為單一無歧義前綴匹配與原生 `String.prototype.trim()`。
@@ -192,74 +229,6 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 - **桌面整合指南**：
   - 新增完整文件 [`docs/desktop-setup.md`](docs/desktop-setup.md)，涵蓋 LM Studio、Roo Code、ChatWise 與 Cherry Studio 步驟指引。
 
-### v6.3.8
-
-- **可執行的互動式工作流啟動器**：
-  - `feature-pipeline` 與 `structured-debug` 會逐階段給出明確的 `read_skill` 呼叫，保留必要的使用者核准關卡，並清楚說明流程由客戶端 Agent 執行，不是 MCP 伺服器內部自動執行。
-  - 支援多 Agent 的 Host 可使用 Subagent；其他 Host 會退回會話內或序列執行，不會聲稱使用不存在的能力。
-  - `read_skill` 同時接受純技能名稱與文件所載的 `superpowers:` 前綴。
-  - Skill Compositions 指南已納入 npm 套件，並可透過 `guide://superpowers/skill-compositions` 讀取。
-- **全域安裝引擎並行安全、Inode 防禦與符號連結跳脫隔離**：
-  - **Allowed Roots 邊界隔離**：強制限制目的地路徑必須在使用者允許目錄（`homeDir`、`appData`、`localAppData`），杜絕父層符號連結跳脫攻擊。
-  - **樂觀並行衝突檢測**：在原子 `fs.renameSync` 前比對磁碟檔案與 `expectedContent`，防止多行程競態覆寫較新的設定檔。
-  - **目錄 Inode & Dev TOCTOU 防禦**：比對暫存檔案目錄之真實裝置與 inode 識別碼，防止目錄置換攻擊。
-  - **Fail-Closed 嚴格解析防護**：JSON 根目錄或伺服器欄位非 Plain Object 時即刻拒絕，阻斷原型污染與畸形設定。
-- **核心技能引擎確定性排序與動態快取驗證**：
-  - **目錄確定性排序與別名衝突防禦**：目錄按字母確定性排序並即時阻擋衝突鍵名，杜絕隨機覆寫與快取錯位。
-  - **自動快取驗證 (`CACHE_REVALIDATE_MS = 1000`)**：磁碟變更在 1 秒內自動同步，無需重啟 MCP 伺服器即可反映檔案編輯。
-  - **大小寫折疊與真實路徑防禦**：`src/server.ts` 在 darwin/win32 進行大小寫折疊與 `fs.realpathSync` 驗證，徹底攔截系統保護目錄（`/private/etc`、`/private/var`、`C:\Windows`）。
-- **RFC 6455 WebSocket 協議加固與日誌彈性壓縮**：
-  - 完整支援 `CONTINUATION` (0x00) 分段訊息重組，並嚴格驗證控制幀不得分段 (`opcode >= 0x8 && !fin`)，阻絕非標準 RSV 擴展。
-  - 尾部彈性日誌壓縮：日誌達 1 MB 上限時保留最新換行對齊記錄，避免整檔抹除遺失事件上下文。
-  - 私有檔案描述元以 `O_RDWR | O_APPEND | O_CREAT | O_NOFOLLOW` 安全開啟。
-- **Shell 與 PowerShell 腳本指令注入防禦**：
-  - `find-polluter.sh` 與 `find-polluter.ps1`：指令參數陣列化展開 (`"${TEST_COMMAND[@]}"`、`& $testCommand @testCommandArgs`) 搭配含空白檔名安全讀取迴圈，杜絕 Shell 注入。
-  - `sdd-workspace`：執行 `cd` 前重設 `CDPATH=''`，阻絕環境變數目錄劫持。
-  - `sdd-workspace.ps1`：以 UTF-8 without BOM (`[System.Text.UTF8Encoding]::new($false)`) 寫入計畫標記，確保無損 Unicode 路徑往返。
-- **全自動化回歸測試底線**：
-  - 擴展測試套件至 **274 項自動化斷言全數通過**（Node.js: 145 項、Bash: 35 項、PowerShell: 94 項），維持 100% 通過率。
-
-### v6.3.7
-
-- **上游同步 — 第 1–3 批（obra/superpowers）**：
-  - **技能自動路由**：`systematic-debugging` 與 `test-driven-development` 的 description 新增觸發詞（`"tdd"`、`"systematic debug"` 等）與兄弟技能交叉導引，提升 MCP 客戶端的技能選擇準確度。
-  - **無測試指令的證據律**：`verification-before-completion` 新增「When There Is No Test Command」章節：報告、研究、稽核與書信類工作必須重新開啟成品、逐項證明並誠實列出未完成項，只能宣稱「完整」而非「正確」。
-  - **Brainstorming 意圖閘門**：新增「Establish Shared Understanding」（探索意圖 → 回寫理解 → 帶入設計），並重寫 HARD-GATE 明列各路徑前置條件，禁止把單次核准當成跳過後續階段的許可。
-  - **規劃交接審查（Planning-Handoff Review）**：brainstorming 的規格自我審查升級為 0.0–9.9 評分 + burden ledger + 單次有界改進 + 唯讀複評，並具備失敗時還原初稿的保底規則。
-  - **已存計畫審閱與情境化交接**：`writing-plans` 要求人類先審閱存檔計畫才可執行；未指定執行方式時必須給出針對本計畫的推薦，而非固定預設。
-  - **計畫勾選簿記**：`executing-plans` 與 `subagent-driven-development` 在完成訊息中同步勾選計畫檔步驟。
-  - **遠端安全邊界**：`using-git-worktrees` 要求從共享 ref 開分支時必須加 `--no-track`，並以 `git branch -vv` 檢查追蹤狀態（首次 commit 前先 `--unset-upstream`）；`executing-plans` 要求 commit 保持本地、禁止改寫共享分支；implementer 遇到任何 push 需求一律回報 BLOCKED，不得自行推送。
-  - **Discoveries 帳本**：SDD 進度帳本新增 `## Discoveries` 區段，跨任務發現可穿越 compaction，並成為下一次派工介面條款的來源。
-  - **延後發現匯出**：刪除計畫工作區前，`Ruling:`／`minor (deferred)`／`parked` 行必須匯出到 PR 的「Deferred items」清單，或提交至 `docs/superpowers/follow-ups/<plan>.md`。
-  - **Greenfield SDD Scripts**：repo 尚未建立時 `sdd-workspace` 退回當前目錄（`.ps1` 同步支援），`review-package` 則在非 repo 環境下給出可行動的錯誤。
-  - **TDD 特徵化守門**：行為保持型重構的五步程序（先變異、確認失敗、由 VCS 還原、維持綠燈），並從邊界與變異檢查章節交叉引用。
-- **上游內容同步 — 第 4 批**：brainstorm 啟動腳本改由 `BRAINSTORM_HOST`/`BRAINSTORM_URL_HOST` 決定 host（`--host`/`--url-host` 仍優先）、`writing-skills` 新增搬移內容時的連結重解指引，SDD 審查者改為把完整報告寫入 `…/task-N-review.md` 並只回傳少於 15 行摘要 — MCP 端新增 `review_file` 參數（若要求的路徑正規化後等於報告或 brief 檔，改用推導出的 `-review.md`），以及讓 `[FIX_BASE_SHA]` 真正被代入的 `fix_base_sha` 別名。
-- **上游 drift 報告**：`npm run drift` 以已提交的上游基線比對 `obra/superpowers`，列出已採納檔案的變動、本地缺漏的引進檔案與 fork 專屬新增；`npm run drift:record -- --ignore <skill>` 於審閱同步後更新基線，且會在寫入前拒絕遭截斷的 API tree。
-- **MCP 表面覆蓋率測試**：磁碟上的每個 skill 都必須是對外曝露、且讀出內容屬於該 skill 的 MCP resource，prompt 清單必須與 4 個 README 完全一致。
-- **MCP 描述保真**：上游的跳脫引號格式改為未加引號的 YAML plain scalar，確保 `SkillsManager` 經 MCP 輸出時不會出現多餘反斜線。
-- **回歸防護**：`tests/upstream_sync_test.js` 增至 22 項標記檢查（涵蓋第 1–4 批）；全測試套件通過（8 個 npm 套件共 139 項檢查、PowerShell 90 項斷言、SDD 16 + host 預設 11 + render-graph 8 項 bash 斷言）。
-- **發佈前強化**：Bash 與 PowerShell 的 brainstorm host 測試明確強制 background 模式，讓完整 264 項驗證在 `CODEX_CI=1` 下也能正常結束；`package-lock.json` 已同步至 v6.3.7 與 Node `>=18`；npm repository 與 CLI `bin` metadata 已正規化，並經 `npm publish --dry-run` 與打包安裝 smoke test 驗證。
-
-### v6.3.6
-
-- **極致效能躍升優化 (2x~8.1x 加速)**：
-  - **並行技能索引與快取前置**：`SkillsManager.listSkills` 升級為非同步並行目錄遍歷 (`Promise.all`) 搭配根目錄預解析快取，冷啟動技能索引延遲由 4.79ms 銳減至 2.35ms（**2.04x 速度提升**）。
-  - **極速記憶體 Canonical 快取**：針對 `readSkillContent` 引入以實體真實路徑為鍵的 Canonical 快取與別名映射機制，二次技能讀取由 0.013ms 驟降至 1.6µs（**8.1x 速度提升**）。
-  - **Frontmatter 切片與 ReDoS 防護**：`parseFrontmatter` 改以 64 KB 前綴緩衝區局部切片取代全檔正則匹配，徹底消除大檔案 GC 停頓與二次方 ReDoS 風險。
-  - **JSON 解析高速直通路徑**：在 `stripJsonComments` (`src/setup-runner.ts`) 引入原生 JSON 嘗試，無註解設定檔讀取速度提升至 0.55µs（**5.1x 速度提升**）。
-  - **並行多目標打包編譯**：`esbuild.js` 採用 `Promise.all` 並行編譯 4 大產物，全專案打包時間降至 ~50ms（**~42% 速度提升**）。
-- **雙子 Subagent 深度 Code Review 與全面缺陷加固 (FIX ALL)**：
-  - **Partial-Read 緩衝區截斷防禦**：`SkillsManager.readFileNoFollow` 實作累加式讀取迴圈（`while (totalRead < fileSize)`），杜絕高併發磁碟 I/O 或虛擬檔案系統下的無聲截斷。
-  - **Scan Epoch 並發版本防護**：`listSkills` 引入遞增的 `scanEpoch` 代數計數器，防止背景慢速掃描覆寫較新的快取狀態。
-  - **Canonical 快取一致性保證**：以實體真實路徑 (`realFilePath`) 為核心鍵值並透過 `canonicalPathMap` 維護別名映射，徹底消除符號連結別名的快取漂移 (Cache Drift)。
-  - **系統黑名單防禦擴展**：`getSafeSkillsPath` 補齊 macOS `/private/etc` 與 `/private/var`，杜絕攻擊者透過環境變數逃逸至敏感系統目錄。
-  - **設定檔寫入符號連結逃逸防禦**：`safeWriteConfig` 在寫入前透過 `fs.lstat` 與真實路徑解析，嚴格拒絕指向敏感系統路徑的符號連結偽造寫入。
-  - **嚴格 TypeScript 與 Rule 7 零瑕疵合規**：徹底清理廢棄死代碼（`exists` 私有方法），全面通過 `--noUnusedLocals --noUnusedParameters`，並消除全專案所有無型別/空白 catch 區塊。
-- **自動化測試套件擴充與基準回歸**：
-  - 全套件 85 項核心單元/端到端測試與 174 項回歸斷言 100% 通過（包含 `setup_test.js` 33 項測試全部通過），並產出 [`SECURITY.md`](SECURITY.md)、[`tests/code_review_report.md`](tests/code_review_report.md) 與 [`tests/performance_optimization_report.md`](tests/performance_optimization_report.md)。
-- **多語系文檔全面對齊**：
-  - 4 語系 README（[`README.md`](README.md)、[`README.zh-TW.md`](README.zh-TW.md)、[`README.ja.md`](README.ja.md)、[`README.ko.md`](README.ko.md)）同步支援環境清單、效能指標與一鍵指令表格。
-
 👉 *更多歷史版本更新紀錄，請參閱完整的 [CHANGELOG.md](CHANGELOG.md)。*
 
 ---

package/docs/skill-compositions.ja.md

@@ -8,7 +8,7 @@
 
 ## 1. スキル構成が重要な理由 (Why Skill Compositions Matter)
 
-`superpowers-mcp` に含まれる 14 のコアスキルは、要件の明確化、アーキテクチャ設計、分離されたワークスペースの構築、テスト駆動開発 (TDD)、体系的なデバッグから、完全検証、コードレビュー、ブランチ統合に至るまで、ソフトウェア開発ライフサイクル (SDLC) 全体を網羅しています。
+`superpowers-mcp` に含まれる 15 のコアスキルは、要件の明確化、アーキテクチャ設計、分離されたワークスペースの構築、テスト駆動開発 (TDD)、体系的なデバッグから、完全検証、コードレビュー、ブランチ統合に至るまで、ソフトウェア開発ライフサイクル (SDLC) 全体を網羅しています。
 
 各スキルは単体でも高精度なエンジニアリングツールですが、実践的な開発には「ワークフローのオーケストレーション（編排）」が不可欠です。スキル構成（Skill Composition）によって、アドホックな AI 操作を、規律ある再現可能で安全保護されたエンジニアリングパイプラインへと昇華させます。
 
@@ -117,6 +117,10 @@ flowchart LR
 4. **`systematic-debugging`**：保護テストで発見された潜在的欠陥を特定・修正。
 5. **`verification-before-completion`**：安全網の完全性を検証。
 
+### メタスキル：セッションフォレンジック (Session Forensics)
+
+4 つのパイプラインの外側で、**`diagnosing-superpowers`** はディスク上のトランスクリプトから過去セッションの問題経緯を再構成します：インテーク、セッション特定、証拠付きの並列アナリスト報告、そして任意でスクラブ済みバンドルや GitHub issue 草案。セッションが計画を無視した、作業を繰り返した、説明不能な結果を出した時に使い、所見が上流に属する場合はメンテナ向け報告も起草します。MCP サーバーはスキル内容の提供のみを担い、エージェントが自身のツールでホストの記録を読むため、トランスクリプトがサーバーを経由することはありません。
+
 ---
 
 ## 4. スキル作成とメタデータ標準 (Skill Authoring & Metadata Standards)
@@ -162,7 +166,7 @@ flowchart LR
 
 ## 6. IDE での実際の操作方法 (How to Use in Practice)
 
-`superpowers-mcp` を設定すれば、**14 個の個別スキル名を覚える必要は一切ありません**。以下の 2 つの方法で簡単に利用できます：
+`superpowers-mcp` を設定すれば、**15 個の個別スキル名を覚える必要は一切ありません**。以下の 2 つの方法で簡単に利用できます：
 
 ### 方法 A: クライアントの MCP Prompts メニューを使用（推奨）
 Cursor、Antigravity、VS Code、Devin Desktop などのチャット入力欄で：

package/docs/skill-compositions.ko.md

@@ -8,7 +8,7 @@
 
 ## 1. 스킬 조합이 중요한 이유 (Why Skill Compositions Matter)
 
-`superpowers-mcp`의 14개 핵심 스킬은 요구사항 명확화, 아키텍처 설계, 격리된 작업 환경 구축, 테스트 주도 개발(TDD), 체계적 디버깅부터 전체 검증, 코드 리뷰, 브랜치 통합에 이르기까지 소프트웨어 개발 라이프사이클(SDLC) 전반을 다룹니다.
+`superpowers-mcp`의 15개 핵심 스킬은 요구사항 명확화, 아키텍처 설계, 격리된 작업 환경 구축, 테스트 주도 개발(TDD), 체계적 디버깅부터 전체 검증, 코드 리뷰, 브랜치 통합에 이르기까지 소프트웨어 개발 라이프사이클(SDLC) 전반을 다룹니다.
 
 각 스킬은 단독으로도 정밀한 엔지니어링 도구 역할을 하지만, 실제 프로덕션 개발에는 **워크플로우 오케스트레이션(편성)**이 필수적입니다. 스킬 조합(Skill Composition)을 통해 임의적인 AI 상호작용을 체계적이고 재현 가능하며 안전하게 보호되는 엔지니어링 파이프라인으로 전환합니다.
 
@@ -117,6 +117,10 @@ flowchart LR
 4. **`systematic-debugging`**: 테스트 추가 과정에서 발견된 잠재 결함 해결.
 5. **`verification-before-completion`**: 자동화된 CI 테스트 장벽 구축.
 
+### 메타 스킬: 세션 포렌식 (Session Forensics)
+
+네 가지 파이프라인 밖에, **`diagnosing-superpowers`**는 디스크의 트랜스크립트에서 과거 세션의 문제 경위를 재구성합니다: 인테이크 인터뷰, 세션 탐색, 인용 증거가 있는 병렬 애널리스트 보고서, 그리고 선택적으로 스크럽된 번들이나 GitHub 이슈 초안. 세션이 계획을 무시했거나 작업을 반복했거나 설명할 수 없는 결과를 냈을 때 사용하고, 소견이 업스트림에 속하면 메인테이너 보고도 대신 작성합니다. MCP 서버는 스킬 내용 제공만 담당하며, 에이전트가 자체 도구로 호스트의 기록 파일을 읽기 때문에 트랜스크립트가 서버를 경유하지 않습니다.
+
 ---
 
 ## 4. 계획 기반 스킬 구성 스키마 (Plan-Driven Skill Metadata Schema)
@@ -162,7 +166,7 @@ flowchart LR
 
 ## 6. IDE에서 실제로 사용하는 방법 (How to Use in Practice)
 
-`superpowers-mcp`를 설정하면 **14개의 개별 스킬 이름을 일일이 기억할 필요가 없습니다**. 아래의 두 가지 간단한 방법으로 시작할 수 있습니다:
+`superpowers-mcp`를 설정하면 **15개의 개별 스킬 이름을 일일이 기억할 필요가 없습니다**. 아래의 두 가지 간단한 방법으로 시작할 수 있습니다:
 
 ### 방법 A: 클라이언트의 MCP Prompts 메뉴 사용 (권장)
 Cursor, Antigravity, VS Code, Devin Desktop 등의 대화창에서:

package/docs/skill-compositions.md

@@ -29,7 +29,7 @@ The same guide is exposed to MCP clients as `guide://superpowers/skill-compositi
 
 ## 2. Why Skill Compositions Matter
 
-The 14 core skills in `superpowers-mcp` span the entire software development lifecycle (SDLC): from requirements discovery, architecture planning, isolated workspace setup, test-driven development (TDD), and systematic debugging, to full verification, code review, and branch integration.
+The 15 core skills in `superpowers-mcp` span the entire software development lifecycle (SDLC): from requirements discovery, architecture planning, isolated workspace setup, test-driven development (TDD), and systematic debugging, to full verification, code review, and branch integration.
 
 While each atomic skill acts as a precision engineering tool, production-grade development requires **workflow orchestration**. Skill compositions transform ad-hoc AI interactions into disciplined, reproducible, and safety-guarded engineering pipelines.
 
@@ -136,6 +136,10 @@ flowchart LR
 4. **`systematic-debugging`**: Root-cause hidden defects surfaced while establishing test baselines.
 5. **`verification-before-completion`**: Solidify automated CI test barriers.
 
+### Meta Skill: Session Forensics
+
+Outside the four pipelines, **`diagnosing-superpowers`** reconstructs what went wrong in a past session from its on-disk transcripts: intake interview, session discovery, parallel analyst reports with cited evidence, then an optional scrubbed bundle or GitHub issue draft. Reach for it when a session ignored the plan, repeated work, or produced a result nobody can explain — and when the finding belongs upstream, it drafts the maintainer report too. The MCP server only serves the skill content; the agent reads the host's transcript files with its own tools, so no transcript ever crosses the server boundary.
+
 ---
 
 ## 5. Plan-Driven Skill Metadata Schema

package/docs/skill-compositions.zh-TW.md

@@ -8,7 +8,7 @@
 
 ## 1. 為什麼需要技能組合 (Why Skill Compositions Matter)
 
-`superpowers-mcp` 的 14 個核心技能涵蓋了現代軟體工程生命週期（SDLC）的各個階段：從需求澄清、架構規劃、隔離實作、TDD 開發、系統化除錯，到全套驗證、代碼審查與分支整合。
+`superpowers-mcp` 的 15 個核心技能涵蓋了現代軟體工程生命週期（SDLC）的各個階段：從需求澄清、架構規劃、隔離實作、TDD 開發、系統化除錯，到全套驗證、代碼審查與分支整合。
 
 單一技能如同「高精度的專業工具」，但真實開發需要「工作流編排（Orchestration）」。透過技能組合（Skill Composition），能將鬆散的 AI 操作轉化為嚴謹、可重複驗證、防護嚴密的工程流水線。
 
@@ -117,6 +117,10 @@ flowchart LR
 4. **`systematic-debugging`**：針對補測試過程中發現的潛在隱患進行根因排查。
 5. **`verification-before-completion`**：建立 CI/CD 測試防線。
 
+### Meta 技能：會話鑑識 (Session Forensics)
+
+四條管線之外，**`diagnosing-superpowers`** 可依據磁碟上的對話紀錄重建過去某次會話的出錯經過：需求訪談、會話定位、多路分析師並行產出附引證的報告，之後可選擇性產出脫敏 bundle 或 GitHub issue 草稿。當某次會話無視計畫、重複勞動，或產出無人能解釋的結果時就用它；若發現應回報上游，它也能代擬維護者報告。MCP server 只負責提供技能內容，Agent 以自身工具讀取主機上的紀錄檔，因此對話紀錄不會經過 server。
+
 ---
 
 ## 4. 計畫驅動的技能編排規格 (Plan-Driven Skill Metadata Schema)
@@ -162,7 +166,7 @@ flowchart LR
 
 ## 6. 如何在 IDE 中實際操作與觸發 (How to Use in Practice)
 
-只要安裝了 `superpowers-mcp`，您**完全不需要手動記住 14 個技能名稱**。有以下兩種最簡單的使用方式：
+只要安裝了 `superpowers-mcp`，您**完全不需要手動記住 15 個技能名稱**。有以下兩種最簡單的使用方式：
 
 ### 方式 A：使用客戶端的 MCP Prompts 選單（最推薦）
 在 Cursor, Antigravity, VS Code 或 Devin Desktop 的對話框中：