plan-close

plan-close — 統一結案（批次 Notion 同步）

將 .spec/{slug}/ 中的所有設計文件一次性批次同步到 Notion，更新狀態，同步到知識庫，並提交設計文件到 Git。整個流程僅 3-5 次 Notion API 呼叫。

---

設定目錄

依 references/config-resolver.md 的漸進式載入邏輯讀取設定。本 Skill 需要：

• 第 1 層：config.md（Notion IDs — 功能設計庫 / 專案資料庫）
• 第 2 層：projects/{repo-id}.md（專案對應、技術棧 ID）
• 第 3 層：stacks/{id}.md（技術棧定義，用於設計庫同步）

Bug 類型還需 bug-workflow 設定檔（~/.claude-company/bug-workflow-config.md 或 ~/.claude/bug-workflow-config.md）。

---

前置條件

• 已使用 /plan-start 建立任務
• 已完成規劃和開發（.spec/{slug}/ 下有設計文件）
• 程式碼已 commit

前置檢查：參照 bug-workflow plugin 的 references/prerequisites.md 執行完整前置檢查（CLAUDE.md + 設定檔 + 專案註冊）。

---

流程

1. 定位活躍任務

與 /plan 相同邏輯。讀取 .spec/{slug}/README.md 取得 type、notion_page_id、notion_url。

2. 收集所有本地設計文件

掃描 .spec/{slug}/ 目錄，列出所有可用文件：

Feature 類型：

檔案	Notion 區塊	存在？
spec.md	📐 技術規格	✅/❌
db.md	🗄️ 資料庫設計	✅/❌
arch.md	🏗️ 架構設計	✅/❌
files.md	📁 程式碼清單	✅/❌
review.md	📋 程式碼審查（新增區塊）	✅/❌
verify.md	🧪 驗證報告（新增區塊）	✅/❌
log.md	📝 開發日誌	✅/❌

Bug 類型：

檔案	Notion 區塊	存在？
investigation.md	🔍 調查過程	✅/❌
root-cause.md	🧠 根因分析	✅/❌
fix.md	✅ 修復方案	✅/❌
log.md	📝 經驗教訓	✅/❌

3. 從 Git 擷取變更摘要

從專案設定檔讀取 prod_branch（PROD 分支），用作 merge-base 計算 diff：

# {prod_branch} 從 projects/{repo-id}.md 的 prod_branch 欄位讀取
git branch --show-current
git log --oneline $(git merge-base HEAD {prod_branch})..HEAD
git diff $(git merge-base HEAD {prod_branch})..HEAD --stat
git diff $(git merge-base HEAD {prod_branch})..HEAD

若 prod_branch 未設定（舊專案），回退邏輯：先取 origin/HEAD 指向的分支，若無則依序嘗試 production → master → main。

根據 CLAUDE.md 的架構描述，產出分層變更摘要。

4. 智慧判斷目標狀態

狀態推斷邏輯：

• 使用者輸入含「完成」、「done」、「上線」、「結案」→ 已完成
• 含「測試」、「QA」→ 測試中
• 無法判斷 → 詢問，預設 測試中

5. 一次性 Notion 批次更新

5-1. Fetch 現有頁面（1 次 notion-fetch）

使用 notion_page_id（從 README.md 取得）fetch 頁面。

5-2. 更新頁面內容（1 次 notion-update-page content）

將所有設計文件內容組合成一次 update_content 操作：

Feature 類型：

📐 技術規格 區塊 ← spec.md 內容
🗄️ 資料庫設計 區塊 ← db.md 內容
🏗️ 架構設計 區塊 ← arch.md 內容
📁 程式碼清單 區塊 ← files.md 內容 + Git diff 產出的分層變更摘要
📝 開發日誌 區塊 ← 附加結案紀錄：
  ### [{日期}] 開發完成
  - **分支**：{branch}
  - **Commit 數**：{N}
  - **變更摘要**：{分層變更摘要}

若 review.md 存在，在「📝 開發日誌」前插入：
📋 程式碼審查 區塊 ← review.md 內容

若 verify.md 存在，在「📋 程式碼審查」後（或「📝 開發日誌」前）插入：
🧪 驗證報告 區塊 ← verify.md 內容

Bug 類型：

🔍 調查過程 區塊 ← investigation.md 內容
🧠 根因分析 區塊 ← root-cause.md 內容
✅ 修復方案 區塊 ← fix.md 內容 + Git diff 分層摘要
📝 經驗教訓 區塊 ← log.md 或自動產生的經驗教訓

5-3. 更新 Properties（1 次 notion-update-page properties）

Feature：

欄位	值
狀態	步驟 4 判斷結果
開發階段	測試中
修復分支	當前 Git branch

Bug：

欄位	值
狀態	步驟 4 判斷結果
根因分類	從 root-cause.md 推斷（邏輯錯誤/資料異常/設定問題/第三方API/效能/權限/前端UI）
修復分支	當前 Git branch

6. 同步到知識庫

Feature → 功能設計庫（1 次 notion-create-pages）

同步邏輯：

欄位	值
Name	功能標題
Tags	自動推測（API/報表/標籤/推播/排程 等）
設計類型	依文件齊全度判斷
技術棧	設定檔中的技術棧 ID
參考連結	Notion 頁面 URL
專案資料庫	同一專案

Bug → Bug 知識庫（1 次 notion-create-pages）

複用 bug-close 的同步邏輯：

欄位	值
Name	Bug 標題
Tags	自動推測
難易度	依修改檔案數和行數判斷
專案資料庫	同一專案
參考連結	Notion 頁面 URL

7. Feature-Bug 關聯（僅 Bug 且有 related_feature）

若 README.md 中 related_feature 不為空：

1. 從 .spec/{related_feature}/README.md 取得 notion_page_id
2. notion-fetch 取得關聯 Feature 的 Notion 頁面（1 次）
3. 在「📝 開發日誌」區塊追加：

### [{日期}] 🔴 相關 Bug
- Bug: {Bug 名稱}（{Bug Notion URL}）
- 根因: {root-cause.md 摘要}
- 修復: {fix.md 摘要}

4. notion-update-page 更新 Feature 頁面（1 次）

8. 提交 .spec/ 設計文件到 Git

將最終版本的設計文件提交：

1. 在 .gitignore 中排除此 slug 的目錄：

   • 追加 !.spec/{slug}/ 到 .gitignore

2. Git 操作：

   git add .spec/{slug}/
   git commit -m "docs: 新增 {slug} 設計文件"
   

9. 更新 _index.md

將任務從「進行中」移至「已完成」區段：

## 已完成

| slug | 類型 | 名稱 | 完成日期 | Notion |
|------|------|------|---------|--------|
| {slug} | {type} | {name} | {日期} | [連結]({url}) |

不刪除 .spec/{slug}/ 目錄，保留供未來 Bug 關聯匹配。

10. 回傳結果

結案完成！

📊 Notion 頁面：{URL}（已更新）
📚 知識庫：{知識庫條目 URL}（已同步）
{📎 Feature 關聯：已更新 {related_feature} 的開發日誌}
📁 設計文件：已提交到 Git

Notion API 呼叫統計：{N} 次（fetch: 1, update: 2, create: 1{, 關聯更新: 2}）

後續事項：
  📋 測試驗證：在 Notion 頁面勾選驗證項目
  🔀 Git 合併：{根據 CLAUDE.md Git Flow 產出合併建議}

---

Gotchas

• 一次 update_content 的大小限制：Notion API request body 約 2MB 上限。大型功能的設計文件（spec.md + db.md + arch.md 合計）可能超過此限制，需分批呼叫 update_content。
• Bug 類型需讀取兩個設定檔：知識庫 ID（Bug 知識庫）在 bug-workflow 設定檔中，只讀 feature-workflow 設定檔會靜默跳過知識庫同步。Bug 類型結案時，兩個 workflow 的設定檔都要讀取。
• .gitignore 排除規則順序敏感：.spec/ 忽略 + !.spec/{slug}/ 取消忽略的規則，可能被 .gitignore 中其他更後面的規則（如 *.bak）再次覆蓋。確保 !.spec/{slug}/ 放在所有相關忽略規則之後。
• Notion 呼叫次數統計：承諾 3-5 次，但 Bug 有 related_feature 時會多 2 次（fetch + update 關聯 Feature 頁面），實際可達 7 次。回傳結果的統計數字要如實反映。

---

邊界情況

• notion_page_id 為空：建議先用 /plan-sync 建立 Notion 條目
• 無設計文件：僅更新 Properties 和開發日誌
• diff 過大（> 500 行）：僅摘要檔案清單和分層變更
• 知識庫 ID 為空：跳過知識庫同步
• related_feature 的 Notion 頁面不存在：跳過關聯更新，提示使用者
• Notion API 失敗：顯示已完成和失敗的步驟，建議用 /plan-sync 重試
• CLAUDE.md 無 Git Flow 描述：使用通用提示