plan-browse

name	plan-browse
description	瀏覽與探索已有的 .spec/ 規劃文件 —— 深度閱讀、跨任務比較、模式搜尋。當使用者提到 /plan-browse、「瀏覽 .spec 規劃」、「看之前的規劃設計」時觸發此 Skill。

plan-browse — 規劃瀏覽器（零 Notion 呼叫）

深度瀏覽 .spec/ 目錄中的規劃。不只是列出任務（那是 /plan-status 的工作），而是讀取、理解、比較、搜尋設計內容。

一個任務的規劃只有一份文件：.spec/{slug}/plan.md（六章節）＋ deploy.sql（唯一 SQL 事實來源）。 流程階段一律唯讀 .spec/{slug}/state.json（只讀，不寫）。本 skill 全程唯讀，不改任何檔。

v1 舊任務：.spec/{slug}/plan.md 不存在 → 這是 v1 結構，依 ../../references/legacy-v1.md 的相容模式執行，並在開頭提示一次。 過渡期限定，到期本段連同該檔一併刪除。

---

使用方式

/plan-browse                         # 互動式瀏覽（列出所有規劃，選擇後深入）
/plan-browse <slug>                  # 深度閱讀指定任務的所有設計文件
/plan-browse --compare <slug1> <slug2>  # 比較兩個任務的設計
/plan-browse --search <關鍵字>        # 跨任務搜尋設計內容
/plan-browse --patterns              # 分析跨任務的共通模式
/plan-browse --timeline              # 按時間軸瀏覽規劃演進

---

與 plan-status 的差異

	/plan-status	/plan-browse
目的	任務管理（狀態、暫停/恢復）	設計內容探索
深度	列出名稱、狀態、分支	讀取並摘要 plan.md 各章節內容
比較	不支援	支援跨任務比較
搜尋	不支援	支援關鍵字搜尋
模式	不支援	分析共通設計模式

---

流程

模式 1：互動式瀏覽（無參數）

1. 用 crew-state.py list --all --format json 取任務清單（slug／name／type／phase／next 等），再只讀每個任務 plan.md 的 frontmatter 與標題下那句需求摘要（🔴 不讀六章節全文，避免任務數多時 token 成本過高）
2. 呈現豐富的總覽（不只是名稱和狀態）：每個任務附一句話摘要 ＋ 階段 ＋ deploy.sql 是否存在；章節細節留待深度閱讀時再讀
3. 輸入編號深入閱讀（進入模式 2 才讀 plan.md 全文），或使用 --compare 1 2 比較兩個規劃、--search <關鍵字> 搜尋設計內容

輸出範本見 references/browse-examples.md（相對 SKILL.md 為 ../../references/）。

模式 2：深度閱讀（指定 slug）

讀 .spec/{slug}/plan.md 全文（六章節）＋ deploy.sql（若存在）＋ 唯讀 state.json（階段、步驟、results、deploy 進度），逐章節產出結構化摘要，並在最後提供「進入探索討論／比較模式／回到 /plan spec|db|arch 補規劃」等後續操作選項。

錨點不展開：「指路」節的 @code: / @sql: 錨點照原樣列出即可。使用者明確追問某個錨點時才去讀它指到的程式碼，不要預先把每個錨點的原始碼撈進摘要（那正是 plan.md 刻意不抄寫的東西）。 章節為空（該 pass 還沒跑）則略過該區塊（見「邊界情況」）。

輸出範本見 references/browse-examples.md（相對 SKILL.md 為 ../../references/）。

模式 3：比較模式（--compare）

讀取兩個任務的 plan.md ＋ deploy.sql，逐層比較（類型、範圍、驗收條件數、決策數與關鍵取捨、DB 表數量、階段），並列出共通點、差異點、可復用的設計。比較的是決策與理由，不是端點數或類別數（那些不在文件裡）。

輸出範本見 references/browse-examples.md（相對 SKILL.md 為 ../../references/）。

模式 4：搜尋模式（--search）

跨所有 .spec/ 目錄搜尋（grep -rn "<關鍵字>" .spec/ --include="plan.md" --include="*.sql"），格式化列出命中的 {slug}/plan.md:{行號} 與上下文摘錄，並標注相關任務與共通模式。state.json 不納入搜尋（機器狀態不是設計內容）。

輸出範本見 references/browse-examples.md（相對 SKILL.md 為 ../../references/）。

模式 5：模式分析（--patterns）

分析所有 plan.md「決策紀錄」「已知取捨與風險」「指路」三節的共通模式：反覆出現的決策取向、DB 設計慣例、被指向最多次的既有元件，各附出現次數與相關任務列表。

輸出範本見 references/browse-examples.md（相對 SKILL.md 為 ../../references/）。

模式 6：時間軸（--timeline）

按時間順序展示規劃演進，樹狀列出每個任務的建立日期、階段，以及底下各流程步驟的完成時間點（唯讀 state.json 的 created 與 steps.{step}.at，🔴 不要用檔案 mtime 猜）。

輸出範本見 references/browse-examples.md（相對 SKILL.md 為 ../../references/）。

---

與其他指令的銜接

瀏覽後使用者可能想：

意圖	建議指令
「這個設計有問題，想討論一下」	/plan-explore <slug>
「想修改目標／驗收條件」	/plan spec（會進入規格確認迴圈）
「想重做 DB／架構設計」	/plan db 或 /plan arch
「文件跟程式碼對不上了」	/plan-drift
「這個可以開始寫了」	/plan-build
「想建立類似的新任務」	/plan-start
「暫停這個任務」	/plan-status --park <slug>

---

何時不用

• 開瀏覽器看網站 → claude-in-chrome / playwright
• 看任務清單與狀態 → /plan-status
• 要推薦下一步 → /plan-next
• 產出新規劃 → /plan（或 /plan spec|db|arch 單跑）
• 檢查 plan.md 錨點與程式碼是否漂移 → /plan-drift

---

Gotchas

• 不要修改任何檔：plan-browse 是唯讀模式 —— 不 Edit plan.md、不呼叫 crew-state.py 的任何寫入子命令（set／unit／result／init…）。使用者想修改就引導到對應的 plan-* 指令或 /plan-explore
• 大量規劃時的效能：如果 .spec/ 下有超過 20 個目錄，互動式瀏覽只顯示最近 10 個（按 state.json 的 updated 排序），並提示使用 --search 或 --timeline 瀏覽全部
• 摘要品質：深度閱讀的摘要應忠於原文，不要添加原文沒有的推測。plan.md 刻意不寫的東西（端點、欄位、類別）就是不在裡面，🔴 不要腦補補齊
• 決策史不要壓縮掉：D-7 取代 D-3 這種 supersede 條目要連同被取代的舊條目一起呈現 —— 決策為什麼改變正是這份文件最有價值的部分
• 比較時保持中立：不自動判定哪個設計「更好」，除非使用者問

---

邊界情況

• .spec/ 不存在：提示「還沒有任何規劃，使用 /plan-start 建立第一個」
• .spec/ 為空：同上
• 指定的 slug 不存在：列出可用的 slug 供選擇
• 規劃不完整（例如只有骨架、六章節都空）：顯示已填的章節，標記空的，並附 crew-state.py next 算出的下一步
• 搜尋無結果：提示「未找到匹配結果」，建議更換關鍵字或使用 /plan-explore 探索
• 只有一個規劃：比較模式不可用，提示改用深度閱讀
• plan.md frontmatter 損壞：顯示警告，改用 state.json 的 name／type 補齊，並提示使用者修 frontmatter
• state.json 缺失或壞掉：提示跑 crew-state.py rebuild --slug {slug}（本 skill 唯讀，不代跑），階段資訊標「未知」而非用檔案存在與否猜