issue-to-mr

name	issue-to-mr
description	從 Issue 分析結果自動產生 Draft MR 建議。需先執行 /issue-analyze 取得影響分析，再根據分析結果產生程式碼修改建議與 Draft MR。當使用者說「issue 轉 MR」、「自動開 MR」、「issue to MR」、「從 issue 建 MR」時觸發。

Issue to MR

從 GitLab Issue 的影響分析結果，產生程式碼修改建議並建立 Draft MR。此 Skill 需要先執行 /issue-analyze 取得分析報告，或在執行時自動觸發分析。

使用方式

/issue-to-mr #123
/issue-to-mr #123 --project=bizform-web
/issue-to-mr #123 --auto-analyze
/issue-to-mr #123 --dry-run

參數

參數	必要	說明
#IID 或 URL	是	目標 Issue
--project	否	目標 MR 的專案 key
--auto-analyze	否	自動先執行 /issue-analyze
--dry-run	否	只顯示建議，不建立 MR

前置條件

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

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

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

• Issue 已有分析報告（或使用 --auto-analyze）

• 信心度必須 >= MEDIUM（50+），LOW 和 INSUFFICIENT 不允許建立 MR

工作流程

Step 1: 前置檢查

• 讀取搜尋到的 .issue-config.json（專案層級優先於使用者層級）
• 檢查 Issue 是否已有 /issue-analyze 報告
  • 若無且有 --auto-analyze → 先執行 analyze
  • 若無且無 --auto-analyze → 提示先執行 /issue-analyze #IID

Step 2: 信心度閘門

讀取分析報告中的信心度分數：

• HIGH (80+): 可以進行
• MEDIUM (50-79): 可以進行，但會在 MR 描述中標註 "Medium confidence - 建議仔細審查"
• LOW (20-49): 顯示警告，使用 AskUserQuestion 詢問是否仍要繼續
• INSUFFICIENT (0-19): 拒絕，提示補充 Issue 描述

Step 3: 修改計畫產生

AI 根據分析報告產生修改計畫：

對每個影響檔案：

1. 使用 get_file_contents 讀取當前檔案完整內容
2. AI 分析需要修改的位置和方式
3. 產生修改建議（修改前/修改後的 diff 預覽）

修改計畫格式：

📋 修改計畫 - Issue #{iid}

檔案 1: src/api/webhook.ts (bizform-web)
  位置: 第 15-20 行
  修改: 移除 pageSize=0，改為分頁參數
  信心度: HIGH

檔案 2: src/hooks/webhook/useWebhooks.ts (bizform-web)
  位置: 第 8-12 行
  修改: 加入分頁 hook
  信心度: MEDIUM

Step 3.5: MR Template 檢查

在建立 MR 前，必須檢查目標 repo 是否有 MR template：

1. 使用 get_repository_tree 查看 .gitlab/merge_request_templates/ 目錄
2. 若存在 template 檔案 → 使用 get_file_contents 讀取
3. 產生 MR 描述時必須遵循 template 格式
4. 將 AI 的修改說明嵌入 template 結構中
5. 保留 template 中的 checklist，並根據修改內容預勾選適當項目

Step 3.6: 測試搜尋與產生

檢查目標 repo 是否有相關的既有測試：

1. 使用 get_repository_tree 搜尋 test/ 或 tests/ 目錄
2. 搜尋與修改檔案相關的既有測試檔案（如修改 NotificationUtils.cs → 尋找 NotificationUtilsTests.cs）
3. 若找到既有測試 → 讀取測試風格和 pattern
4. 產生新測試檔案，遵循既有風格
5. 將測試一併包含在 MR 的修改計畫中

Step 4: 安全審查

安全策略檢查（不可跳過）：

1. 檔案白名單/黑名單檢查

   • 不得修改: CI/CD、secrets、infrastructure、config 相關檔案
   • 只允許修改: 原始碼檔案（.cs, .ts, .tsx, .js, .jsx, .vue 等）

2. 變更範圍檢查

   • 單次 MR 最多修改 analyze.maxFilesPerMR（預設 5）個檔案
   • 單個檔案最多修改 100 行
   • 不得刪除整個檔案

3. 敏感模式偵測

   • 若修改涉及認證、授權、加密相關程式碼 → 強制標記 needs-security-review

4. using / import 完整性檢查

   • 檢查新增的程式碼是否引用了新的型別
   • 確認所有必要的 using 語句（C#）或 import 語句（TS/JS）已包含
   • 比對修改前後的 using 清單，確保新增使用的型別都有對應的 using

Step 5: 預覽與確認

使用 AskUserQuestion 展示完整修改計畫：

問題： 「即將為 Issue #{iid} 建立 Draft MR，確認修改計畫？」

顯示：

• 目標專案和分支
• 每個檔案的 diff 預覽
• MR 標題和描述預覽（遵循 repo template）
• Labels: ai-generated, draft
• 新增/修改的測試檔案

選項：

1. 確認，建立 Draft MR
2. 修改計畫
3. 只建立部分修改
4. 取消

Step 6: 建立 Draft MR

建立流程：

1. 建立新分支: ai/issue-{iid}-{short-title}
2. 依序修改每個檔案（使用 create_or_update_file）
3. 建立 Draft MR:
   • title: Draft: [AI] {Issue title}
   • description: 遵循 repo 的 MR template，包含修改說明、原 Issue 連結、信心度標記、安全審查結果
   • labels: ai-generated + 原 Issue labels
   • draft: true
   • squash: true
   • remove_source_branch: true

Step 7: Pipeline 監控與自動修正（方案 B 自驗）

MR 建立後，自動進入 pipeline 監控循環：

最大重試次數: 3
監控間隔: 30 秒

7.1 等待 Pipeline 觸發

1. 使用 list_pipelines 查詢目標分支的最新 pipeline
2. 若 pipeline 尚未建立 → 等待 30 秒後重試
3. 記錄 pipeline ID

7.2 監控 Pipeline 狀態

1. 使用 get_pipeline 輪詢 pipeline 狀態
2. 狀態處理：
   • pending / running → 繼續等待
   • success → 進入 Step 8（回寫成功）
   • failed → 進入 7.3（錯誤分析）
   • canceled → 報告取消，結束

7.3 錯誤分析

1. 使用 list_pipeline_jobs 找到失敗的 job（scope=failed）
2. 使用 get_pipeline_job_output 讀取失敗 job 的 log（limit=200）
3. AI 分析錯誤類型：

錯誤類型	處理方式
編譯錯誤（CS/TS error）	可自動修正 → 7.4
缺少 using/import	可自動修正 → 7.4
測試失敗	可嘗試修正 → 7.4（最多 1 次）
環境/infra 錯誤	不可修正 → 報告後結束
風格/lint 警告（非 error）	可嘗試修正 → 7.4

7.4 自動修正

1. 根據錯誤分析結果，產生修正
2. 使用 create_or_update_file 推送修正到同一分支
3. commit message: fix: {錯誤描述}
4. 等待新 pipeline 觸發
5. 回到 7.2 繼續監控

7.5 重試上限

若 3 次修正後仍失敗：

1. 回寫 Issue 報告失敗原因
2. 在 MR 加入 comment 說明剩餘問題
3. 提示使用者需要人工介入

Step 8: 回寫 Issue

使用 GraphQL createNote mutation 在 Issue 討論串新增備註：

mutation CreateNote($noteableId: NoteableID!, $body: String!) {
  createNote(input: { noteableId: $noteableId, body: $body }) {
    note { id url }
    errors
  }
}

noteableId 格式: gid://gitlab/Issue/{id}（注意是 id 不是 iid，需從 get_issue 取得）

備註內容：

## 🤖 AI Draft MR 已建立

**MR !{mr_iid}** — [標題](URL)

<details>
<summary>變更檔案摘要（N 個檔案）</summary>

| 檔案 | 變更 |
|------|------|
| `file1.cs` | 變更描述 |

</details>

### Pipeline 狀態: ✅ 通過 / ❌ 失敗（需人工介入）

---
*由 `/issue-to-mr` 自動產生*

Step 9: 完成訊息

✓ Draft MR 已建立: !{mr_iid}

  Issue: #{iid} - {title}
  專案: {project}
  分支: ai/issue-{iid}-{short-title}
  Labels: ai-generated
  Pipeline: ✅ 通過 / ❌ 失敗（原因）

  修改檔案:
  - {file1} (+{added} -{removed})
  - {file2} (+{added} -{removed})

  ⚠️ 這是 AI 自動產生的 Draft MR，請務必人工審查後再合併。

GitLab MCP 工具使用

Step	工具	用途
1	get_issue	取得 Issue（含分析報告）
3	get_file_contents	讀取要修改的檔案
3.5	get_repository_tree	檢查 MR template
3.5	get_file_contents	讀取 MR template
3.6	get_repository_tree	搜尋測試目錄
3.6	get_file_contents	讀取既有測試風格
4	—	using/import 完整性靜態分析
6	create_branch	建立新分支
6	create_or_update_file	修改檔案
6	create_merge_request	建立 Draft MR
7	list_pipelines	查詢 pipeline
7	get_pipeline	監控 pipeline 狀態
7	list_pipeline_jobs	找失敗 job
7	get_pipeline_job_output	讀取 job log
7.4	create_or_update_file	推送自動修正
8	execute_graphql	回寫 Issue（createNote）

安全機制

四重安全閘門

1. 信心度閘門：LOW/INSUFFICIENT 的分析不允許自動產生 MR
2. 檔案安全策略：白名單/黑名單雙重過濾
3. 強制 Draft：所有 AI 產生的 MR 必須為 Draft 狀態
4. 自動修正上限：最多 3 次自動修正，防止無限循環

必加 Labels

• ai-generated — 標記為 AI 產生
• 若涉及安全相關修改 → needs-security-review

不可省略的人工審查

• MR 描述中必須包含審查提示
• 不可自動 approve 或 merge
• 不可移除 Draft 狀態

注意事項

• 所有建立操作需使用者明確確認
• Draft MR 的分支命名規則: ai/issue-{iid}-{short-title}
• AI 產生的程式碼不保證正確，必須人工審查
• 單次 MR 修改範圍不應過大（建議 5 檔案以內）
• 若修改跨多個專案，每個專案建立獨立的 MR
• create_issue_note 有 404 bug，回寫一律使用 GraphQL createNote mutation
• 修改程式碼時，務必檢查 using/import 語句完整性（常見漏洞）
• 推送前必須讀取 repo 的 MR template

範例

基本使用

# 從已分析的 Issue 建立 MR
/issue-to-mr #123

# 自動先分析再建立 MR
/issue-to-mr #123 --auto-analyze

# 只產生修改建議，不實際建立 MR
/issue-to-mr #123 --dry-run

# 指定目標專案
/issue-to-mr #123 --project=bizform-api

工作流程範例

# 1. 先分析 Issue
/issue-analyze #123

# 2. 審查分析結果，確認信心度

# 3. 產生 Draft MR（自動監控 pipeline）
/issue-to-mr #123

# 4. AI 自動監控 pipeline，修正編譯錯誤（最多 3 次）

# 5. Pipeline 通過後，在 GitLab 審查 MR

# 6. 移除 Draft 狀態，進入正常 Code Review 流程

實施狀態

• Phase 1: Issue 分析與影響範圍偵測 ✅
• Phase 2: 自動產生 Draft MR ✅
• Phase 2.5: Pipeline 自驗與自動修正 ✅
• Phase 3: Collaborator（自動測試、CI 整合）🚧