Bug Report

bug-report

⚙️ 執行前先讀 modules/config-loader.md，載入組織設定（JIRA / Slack / 平台預設）。 若 config.json 不存在或 mode = markdown-only，跳過所有 MCP 呼叫並走 modules/markdown-fallback.md。

RIDER + Root Cause 格式

Bug 報告的內容要涵蓋 RIDER 五個分類。詳細說明和範例見 rider-format.md。

⚠️ RIDER 只是內容分類的代稱，不是排版規則。 實際寫進 JIRA Description 時不要用「## R — Reproduction Steps」這種字母前綴標題，要用純中文 H2 標題（## Bug 描述 / ## 重現步驟 (Reproduction) / ## 預期行為 / ## 實際行為 / ## 環境資訊 (Device/Environment)，環境資訊用表格 / ## 影響範圍 (Impact) / ## Root Cause 分析 / ## 相關 Issue），這是團隊既有格式（範例：UOP-6804），完整模板見 templates.md。

⚠️ Root Cause 分析是獨立的必填區塊，不是 References 底下的附屬項目。 每張 bug ticket 的 JIRA Description 都必須包含 RIDER 五要素對應的內容 加上 一個獨立的「Root Cause 分析」段落（Phase 3 的產出，含「可能根因」「與既有 Bug 的關聯」「建議排查方向」三個子項）加上「相關 Issue」段落（父系 Epic / 相關 ticket / 測試用例）。即使是 suggestion-only 深度（無 repo 可查），也要寫出「可能原因」與「建議修復方向」，不可整段省略或留白。

執行模式

模式 1: 互動式問答（預設）

依 Phase 1→6 逐步執行，每個 Phase 完成後才進入下一步。

模式 2: 快速模式（使用者一次提供完整資訊）

直接解析資訊 → Phase 2 查重 → Phase 3 Root Cause → Phase 4 建 JIRA → Phase 5 同步 → Phase 6 追蹤

模式 3: 從 Google Sheet 測試用例批次生成

需要 config.json#mode != markdown-only 且 google.qa_tc_folder_id 已設定。

1. 讀取 Google Sheet（status sheet + 測試用例 sheet）
2. 篩選 Column C = Fail 的項目
3. 檢查 Column N 是否已有 JIRA ticket → 有則跳過
4. 對每個 Fail 項目執行 Phase 2~4
5. 回寫 ticket 號碼到 Google Sheet Column N
6. 發送 Slack DM 彙總通知（依 slack.notification_rules.bug_report）

6 Phase 標準流程

Phase 1: 資訊收集

必備環境資訊（不完整要主動問）：

版本→分支對應（Root Cause 分析需要）：

# iOS — 找 release/testing 分支
gh api repos/{{IOS_REPO}}/branches --jq '.[].name' --paginate | grep "{version}"
# Android — 找 tag（若 default branch 不是 release 用）
gh api "repos/{{ANDROID_REPO}}/tags?per_page=10" --jq '.[] | .name'

若 {{IOS_REPO}} / {{ANDROID_REPO}} 為空，跳過版本→分支對應步驟，直接以 default branch 分析。

Phase 2: 查重

建 JIRA 前必須搜尋是否已有相同/類似 ticket：

JQL: project = {{JIRA_PROJECT_KEY}} AND summary ~ "關鍵字" AND status != Done ORDER BY created DESC
JQL: project = {{JIRA_PROJECT_KEY}} AND parent = {{JIRA_PROJECT_KEY}}-XXXX AND issuetype = Bug ORDER BY created DESC

• 找到相同 → 不開新的，在既有 ticket 加 comment 補充
• 找到類似 → 開新的，description 中 reference 相關 ticket

Phase 3: Root Cause 分析

依據 config.json#workflow.auto_root_cause_depth 決定深度：

deep 模式步驟：

1. 版本差異分析 — 比較測試版本 vs 前一版本：

   gh api "repos/{{IOS_REPO}}/compare/{prev}...{current}" --jq '{
     total_commits, changed_files: [.files[].filename] | length
   }'
   

2. 篩選相關檔案 — 用關鍵字過濾變更檔案
3. 用正確分支讀程式碼 — git show origin/{branch}:{path} 或 GitHub API
4. 檢查是否已修復 — 搜尋 main/develop 是否有 fix commit
5. 跨平台比對（若 workflow.auto_cross_platform_check = true）— iOS 有問題時也查 Android 對應程式碼，反之亦然

Phase 4: 建立 JIRA Ticket

RIDER + Root Cause 格式填入 JIRA Description（模板見 templates.md）。Root Cause 分析段落必填——直接沿用 Phase 3 的產出，不得因為「還沒查」或「不確定」而整段跳過；suggestion-only 深度下至少要有可能原因與修復方向兩項。

JIRA 欄位設定：

附件上傳（JIRA MCP 不支援檔案上傳）：

1. uploadFileToDrive 上傳到 Google Drive
2. set_drive_file_permissions → link_sharing = reader
3. addCommentToJiraIssue 貼 Google Drive 連結
4. 命名規則：{ticket號}_{描述}.{副檔名}

若 config.json#mode = markdown-only 或 atlassian MCP 不可用，改走 modules/markdown-fallback.md 產出 bug-{slug}.md 檔案。

Phase 5: 同步更新

Google Sheet 回寫（如 Bug 來自測試用例）：

• Column C → Fail
• Column D → 失敗原因描述
• Column N → =HYPERLINK("{{JIRA_INSTANCE_URL}}/browse/{{JIRA_PROJECT_KEY}}-xxxx", "{{JIRA_PROJECT_KEY}}-xxxx")

通知（依 config.notifications.enabled_channels 可多管道並存）：

• Slack（MCP，依 slack.notification_rules.bug_report）：dm → {{SLACK_USER_ID}}、channel → {{SLACK_BUG_CHANNEL_ID}}
• Telegram / Line：見 modules/multichannel-notify.md（走 Bot API curl，token 從 config）
• 內容：ticket 號、標題、priority、關鍵資訊

跨平台驗證建議（若 workflow.auto_cross_platform_check = true，每次必做）：

• iOS 有問題 → 主動建議驗證 Android 同一場景
• Android 有問題 → 主動建議驗證 iOS 同一場景
• 另一平台也有問題 → 在同一 ticket 補充或開新 ticket（用 Relates 連結）

a11y 自動配對（若 workflow.auto_a11y_pairing = true）：

• a11y 相關 bug 預設開一對 iOS + Android ticket，並用 Relates 連結

Phase 6: 後續追蹤

建完 ticket 後提醒使用者：

1. Bug 修復後需要重新驗證
2. 驗證通過 → 更新 Google Sheet（Fail → Pass）
3. 檢查此場景是否有對應 test case，沒有的話建議補上（→ test-master skill）

品質檢查

生成前自動驗證：

• 重現步驟清楚可執行
• 預期 vs 實際行為明確
• 環境資訊完整（9 項必填/條件必填）
• 嚴重度與影響範圍一致
• 避免主觀描述（「很慢」→「載入 > 5 秒」）
• 不包含敏感資訊（密碼、Token、個資用 [已遮蔽]）
• 已執行 Phase 2 查重
• 已執行 Phase 3 並在 JIRA Description 寫入獨立的「Root Cause 分析」段落（可能根因 + 與既有 Bug 的關聯 + 建議排查方向，deep 模式再加相關程式碼 file:line）——沒有這個段落不算完成，不可只在 References 提一句「待查」
• 標題全部用純中文 H2（不加 R/I/D/E/R 字母前綴），環境資訊用表格，結尾有「相關 Issue」段落（父系 Epic / 相關 ticket / 測試用例）——格式對照範例 UOP-6804

報告模板

詳見 templates.md（含互動式模板和 JIRA Description 模板）

範例

詳見 examples.md

整合其他 Skill

• 測試計劃中發現 Bug → 自動觸發 bug-report
• Bug 修復後 → test-master 補充防護測試
• Code Review 發現問題 → 詢問建立 Bug 報告或 Task

設定依賴