issue-organize

name	issue-organize
description	批量整理舊有 GitLab Issue，補充標籤、建立關聯、重新分類。當使用者說「整理 issue」、「organize issues」、「清理 issue」、「整理舊 issue」時觸發。

Issue Organize

批量智慧整理舊有 GitLab Issue。AI 分析所有 Issue 後，建議標籤補充、關聯建立、描述完善等改進方案，經確認後批量執行。

使用方式

基本用法（整理所有開放 Issue）

/issue-organize

指定範圍

/issue-organize --milestone="Sprint 60"

指定標籤過濾

/issue-organize --labels=backend,performance

指定狀態

/issue-organize --state=all

參數說明：

• --milestone（可選）：限定特定里程碑的 Issue
• --labels（可選）：限定特定標籤的 Issue
• --state（可選）：opened（預設）/ closed / all
• --limit（可選）：最多處理的 Issue 數量（預設來自 config 的 batchLimit）

前置條件

需要 .issue-config.json 存在。按以下優先順序搜尋：

1. 專案目錄: ./.issue-config.json
2. 使用者目錄: ~/.claude/.issue-config.json

若均不存在，提示：「找不到 .issue-config.json，請先執行 /issue-init 建立設定。」

工作流程

1. 讀取設定

從搜尋到的 .issue-config.json 讀取（專案層級優先於使用者層級）：

• gitlab.defaultProjectPath
• defaults.batchLimit（預設 50）
• defaults.dryRun（預設 true）
• organize.staleDays（預設 90）
• organize.autoLabels（預設 true）
• templates（用於分類參考）

2. 拉取 Issue 清單

使用 mcp__GitLab_communication_server__list_issues 取得目標範圍的 Issue：

• 依據參數過濾（milestone、labels、state）
• 分頁處理（每頁 100 筆，尊重 batchLimit 上限）

使用 mcp__GitLab_communication_server__list_labels 取得專案現有標籤。

顯示：

📋 已載入 47 個 Issue（開放狀態）
   現有 Labels: bug, feature, task, backend, frontend, ...

3. AI 批量分析

AI 對所有載入的 Issue 進行分析，產生「變更計畫」：

分析面向：

a. 標籤缺失或不一致

• 有描述但缺少分類標籤（如 bug/feature/task）
• 標籤與內容不符
• 缺少模組標籤（如 backend/frontend）

b. 可建立關聯的 Issue

• 標題或描述中提到其他 Issue（如 "參見 #123"）
• 內容相關但尚未建立連結的 Issue
• 可能重複的 Issue

c. 描述不完整

• 缺少重現步驟（bug 類）
• 缺少驗收條件（feature 類）
• 描述過於簡短

d. 過期 Issue 標記

• 超過 staleDays 未更新的 Issue

4. 產生變更計畫

以結構化格式顯示建議的變更：

📋 變更計畫（共 12 項建議）

【標籤補充】 5 個 Issue
┌─────┬────────────────────────┬───────────────┬──────────────────┐
│ IID │ 標題                   │ 現有 Labels   │ 建議新增 Labels  │
├─────┼────────────────────────┼───────────────┼──────────────────┤
│ #89 │ 表單送出後沒有回應     │ (無)          │ bug, frontend    │
│ #92 │ 新增匯出 CSV 功能      │ feature       │ backend          │
│ #95 │ 重構 API 路由結構      │ (無)          │ task, backend    │
└─────┴────────────────────────┴───────────────┴──────────────────┘

【建議關聯】 3 組
┌──────────┬──────────┬──────────────────────────┐
│ Issue A  │ Issue B  │ 關聯原因                 │
├──────────┼──────────┼──────────────────────────┤
│ #89      │ #91      │ 相似問題：表單送出相關   │
│ #92      │ #96      │ #96 的描述提到 #92       │
└──────────┴──────────┴──────────────────────────┘

【過期標記】 4 個 Issue
  #45, #52, #61, #68 - 超過 90 天未更新

5. 確認變更

使用 AskUserQuestion：

• 問題：「以上是整理建議，請選擇要執行的項目」
• 選項：
  1. 全部執行（推薦）
  2. 只執行標籤補充
  3. 只執行關聯建立
  4. 逐項確認
  5. 取消

若選擇「逐項確認」，對每個變更逐一詢問。

6. 批量執行

dryRun 判斷邏輯：

若 defaults.dryRun 為 true：

• 只顯示「將會執行」的變更清單，不實際呼叫 API
• 提示：「目前為 dryRun 模式，以上變更不會實際執行。若要執行，請在 .issue-config.json 中設定 defaults.dryRun 為 false，或使用 --execute 參數。」
• 跳到完成報告（Step 7），但標記為「模擬執行」

若 defaults.dryRun 為 false（或使用 --execute 參數），依確認的變更計畫批量執行：

• 標籤補充：mcp__GitLab_communication_server__update_issue（更新 labels）
• 建立關聯：mcp__GitLab_communication_server__create_issue_link（建立 relates_to）
• 過期標記：mcp__GitLab_communication_server__update_issue（新增 stale 標籤）

每處理 10 個 Issue 回報一次進度：

⏳ 進度: 10/12 項變更已執行...

7. 完成報告

✓ Issue 整理完成！

執行摘要：
  ✓ 標籤補充: 5 個 Issue 已更新
  ✓ 關聯建立: 3 組關聯已建立
  ✓ 過期標記: 4 個 Issue 已標記 stale

  跳過: 0 項（全部成功）

GitLab MCP 工具使用

步驟	工具	用途
載入 Issue	list_issues	批量取得 Issue 清單
載入標籤	list_labels	取得現有標籤
查詢關聯	list_issue_links	檢查既有關聯
更新 Issue	update_issue	補充標籤、描述
建立關聯	create_issue_link	建立 Issue 間關聯
建立標籤	create_label	若需要的標籤不存在

安全機制

• dryRun 預設開啟：首次使用時只顯示建議，不實際執行
• batchLimit：單次最多處理的 Issue 數量（預設 50）
• 不會刪除：永遠不刪除任何 Issue
• 不會關閉：不會自動關閉任何 Issue（過期只加標籤）
• 可回溯：每個變更都記錄 before/after，完成報告中可看到

注意事項

• 大量 Issue 的分頁處理可能需要數分鐘
• AI 分析品質取決於 Issue 描述的充分度
• 建議先用 --limit=10 小範圍測試，確認 AI 建議品質後再擴大範圍
• 標籤建議基於 config 中定義的模板和現有標籤系統