snuffish/plan

技能：/plan — 實作計畫管理器

管理當前會話的實作計畫 (<prefix>-implementation_plan-<suffix>.md)。此技能擁有計畫的骨架、其狀態值、連結區塊以及審查（--review）功能。其他所有會寫入或讀取計畫的指令（/implement-feature、/problem、/refine、/pr-fix-pipeline、/proceed）均使用此處定義的規範。

---

模組

路徑相對於此技能的實際資料夾。請對此技能的基本目錄執行一次 realpath（它可能是個符號連結），然後從該處解析每個路徑。如果無法讀取任何模組，請停止並回報該路徑。缺少模組時請不要繼續。

請在步驟 1 之前閱讀以下內容：

• ../_modules/core.md
• ../_modules/artifact-protocol.md：在工件目錄中寫入 <prefix>-implementation_plan-<suffix>.md（artifact-protocol）
• ../_modules/project-profile.md：僅基礎設定檔（無指令設定檔），用於審查（案例 D）；讀取_每層的參考資料_、合約接觸點、_同層鏈_以及可選的_計畫審查檢查_欄位

隨需參考（references/）：

• references/review.md — 五大審查支柱（案例 D 步驟 3）以及 --review（案例 D）和自我審查（案例 B 步驟 4）的報告範本

---

1. 計畫合約

狀態值

計畫的第二行需包含 **Status:** <值>，其值為以下之一：

值	意義	由誰設定
Draft	正在撰寫中；尚未準備好審查	撰寫者，在起草過程中
Awaiting User Review	已完成，正在閘口等待	撰寫者，在呈現計畫時
Approved	使用者打開了閘門；實作正在進行	core › /proceed 閘門
Completed	範圍內的所有階段已完成並驗證	core › /proceed 閘門

值後面可以加上簡短備註（Approved — phase 2 of 3 done）。讀取器僅比對前導值。

骨架

<!-- artifact-owner: … -->                 <!-- artifact-protocol › Claim -->

# Implementation Plan: <title>

**Status:** Awaiting User Review
**Suffix:** `<suffix>`
**Inputs:** <investigation / review / ticket links, or "none">
**Review:** <_Case D_ verdict after folding> · <n> findings folded <!-- Case B step 4 -->

## 1. Context & Goal

## 2. Decisions <!-- table: decision · why -->

## 3. Proposed Changes <!-- per phase or per repo: [NEW|MODIFY|DELETE] <path> — what and why -->

## 4. Verification Plan <!-- exact commands, plus manual steps -->

## 5. Risks <!-- table: risk · mitigation -->

## 6. Task Checklist <!-- the live checklist: [ ] / [/] / [x] -->

## 7. Open Questions <!-- unresolved questions; always last, if any; each with a recommendation -->

指令可以新增其所需的章節（/implement-feature 會新增_使用者審查要求_、盲點檢查_和_跨倉庫順序）。它會保留這七個章節及其順序，以便 /plan、/plan --review 和 /proceed 能找到它們。開放問題（未解決的問題）始終是最後一個章節；新增的章節會放在它之前。

風格

使用者的規則（~/.claude/CLAUDE.md › Plan Mode）適用：極度簡潔，可犧牲文法；結尾需為步驟，然後是未解決的問題（每個問題附帶建議，若無則省略）。

每個計畫撰寫者都需將其應用於整個檔案以及呈現計畫的聊天回覆：

• 使用片段，而非散文：無段落，無完整句子解釋。
• 一個要點一個想法；較長的點請拆分為子要點。
• _決策_和_風險_使用表格。
• 每個開放問題都帶有 Rec: 以及建議的答案。
• _開放問題_之後無任何內容。如果沒有未解決的問題，請註明「None」（或省略）。

連結區塊

每個呈現計畫的聊天回覆都以 artifact-protocol › Chat link block（從 grep -n '^#\{1,3\} ' <file> 取得真實行號，於寫入檔案後執行）開頭，連結到 Context & Goal、Proposed Changes、Verification Plan 和 Open Questions，其後緊接 **Status:** <值>。指令可以在每個章節連結後附加一行摘要（/plan --review 就是這樣做的）。

---

2. 核心行為

從引數中選取案例，首個匹配者獲勝：

引數	案例
包含 --review	D：審查計畫
以 preview 開頭	C：預覽
無	A：純粹
其他任何內容	B：起草或更新

案例 A：純粹指令（/plan 不帶引數或訊息）

1. 定位計畫： 掃描工件目錄（artifact-protocol）中是否有 <prefix>-implementation_plan-*.md，並根據 artifact-protocol › Claim › Readers & family selection 選擇計畫家族（告知使用者下次可使用 /plan <suffix> 跳過提示）。如果不存在，請告知使用者，並提議根據他們的下一個提示建立一個。
2. 呈現連結區塊（§1 連結區塊）給所選計畫，包含其當前 Status。不要編輯任何內容或執行背景指令。

案例 B：帶有指令的指令（/plan <instructions>）

1. 解析上下文相關的後綴，根據 artifact-protocol › 規則 2。
2. 規劃，但不更改程式碼：
   • 首先檢查是否有現有的調查。 如果工件目錄（artifact-protocol）中存在 <prefix>-investigation-<suffix>.md 且涵蓋此主題，則在其基礎上建構：使用其_計畫種子_、選項與權衡_和_信心分類帳。不要重新執行它已記錄的研究；但請解決計畫所依賴的任何 ❓ 未知項。
   • 否則，以唯讀方式研究相關程式碼。如果主題很大或未知項很多，請先執行 /investigate。
   • 根據專案自身的慣例進行設計：其工作區規則手冊、專案範圍的參考資料和設定檔（core › Precedence）。
3. 在工件目錄（artifact-protocol）中，以 §1 骨架 的格式撰寫計畫：
   • 新計畫： 在會話私有的路徑中起草，然後透過 Claim（artifact-protocol › 規則 4）發布。如果基本名稱已被佔用，Claim 會寫入 …-2.md；請使用它輸出的路徑，並在聊天中告知。
   • 現有計畫： 僅當其所有者標記命名此會話，或使用者指定了該檔案並要求更新時，才對其進行更新（artifact-protocol › 規則 3）。否則，透過 Claim 撰寫一個新版本，並在 Inputs 中連結它所取代的版本。
   • 完成後將 Status 設為 Awaiting User Review。在 Antigravity 環境下，當在 <appDataDir>/brain/<conversation-id>/ 內部撰寫鏡像工件副本時，請在 ArtifactMetadata 中設定 UserFacing = true 和 RequestFeedback = true（在工件目錄檔案中省略 ArtifactMetadata）。
4. 在呈現前進行自我審查： 閱讀 references/review.md 並在主上下文中對剛寫入的計畫執行 案例 D 的步驟 2-3。使用其支柱和嚴重性等級。不要列印其報告或閘門：這是起草過程的一部分，使用者審查的是摺疊後的計畫。

   • 在呈現之前，將每個發現摺疊進計畫中：

     發現	放入
     🔴 / 🟡，已驗證（path:line 重新開啟）	Proposed Changes、Task Checklist，以及一個沒有此修正就會失敗的 Verification Plan 檢查
     🔴 / 🟡 需要使用者決策	Open Questions，附帶 Rec:
     🟢	如果是一行則應用；否則丟棄
     被拒絕的發現	Risks，一行，說明原因

   • 重新閱讀一次計畫，檢查是否有任何與修正矛盾的內容（先前的步驟、測試、決策行），並修正它。

   • 只執行一次審查。在 Review: 標題行中填入摺疊後計畫將得到的裁決。

   • 對每個新計畫，以及每次更改了 Proposed Changes 或 Verification Plan 的更新，都執行此審查。對於僅勾選清單或更改 Status 的更新，則跳過。

5. 呈現計畫： 連結區塊（§1 連結區塊）、審查裁決和改變了設計的發現（每個一條要點）、關鍵決策以片段要點呈現，最後是開放問題，每個問題附帶其 Rec:（§1 風格 也適用於此聊天文字：無段落，無完整句子）。在使用者打開閘門（core › /proceed 閘門）之前，等待使用者操作，不要進行任何程式碼更改。

案例 C：預覽指令（/plan preview [target]）

在宿主的規劃預覽面板中顯示一個現有計畫（如果可能，使用 ExitPlanMode），以便使用者可以互動式地閱讀、評論和批准它。

1. 解析計畫： 使用引數（路徑或後綴）、當前會話的活躍計畫檔案，或工件目錄中最新的計畫家族（案例 A）。
2. 宿主能力檢查： 如果宿主缺少 ExitPlanMode（例如 Antigravity IDE），則輸出計畫的連結區塊（案例 A）並解釋宿主直接透過 Markdown 連結渲染計畫。
3. 進入計畫模式並複製： 呼叫 EnterPlanMode，從系統訊息中讀取宿主計畫檔案路徑，並將來源計畫複製到該路徑（省略前導的 <!-- artifact-owner: … --> 註解）。
4. 開啟預覽： 呼叫 ExitPlanMode。
5. 處理決策：
   • 批准：使用者授權實作（core › /proceed 閘門）。開始執行。
   • 繼續規劃 / 回饋：保持在計畫模式，將回饋傳遞給案例 B 以更新計畫，然後重新開啟預覽。
   • 關閉 / 錯誤：報告狀態並提供檔案連結。

案例 D：審查指令（/plan --review [target]）

對實作計畫、架構提案或變更設計進行嚴格、唯讀的審計，在編寫任何程式碼之前。在 /proceed（core › /proceed 閘門）之前保持唯讀：

• 即使計畫完美無缺，也絕不編輯檔案、執行修改性指令（遷移、提交、搭建腳手架）或開始實作。
• 在 --review 下的每個回覆，包括後續追問，都以連結區塊開頭：使用者經常關閉計畫頁籤並從聊天中重新開啟。

錯誤工具：

情況	應改用
程式碼差異、分支或 PR，而非計畫	/code-review
PR 上的審查者評論和投票	/pr-feedback-review
在計畫存在之前的研究	/investigate
設計的隱藏假設和失敗模式	/what-am-I-missing

閱讀 references/review.md 並執行 案例 D 的步驟 1-4（步驟 1：定位計畫；步驟 2：閱讀專案規則；案例 D 步驟 3：根據五大支柱 + 設定檔中的_計畫審查檢查_進行評估；步驟 4：呈現連結區塊和審查報告），然後等待在 core › /proceed 閘門。