diagnose-ci-failures

diagnose-ci-failures

以程式化方式診斷 PR 的 CI 失敗，並生成修復計畫。

概述

此技能提供一個確定性的工作流程，用於檢查 PR 的 CI 狀態、提取失敗日誌、分析錯誤，並建立計畫（而非程式碼變更）來解決問題。輸出始終是一份可供審查的計畫文件。

工作流程

1. 確認目前分支存在 PR

取得目前分支，並檢查是否有對應的 PR：

# 取得目前分支
git branch --show-current

# 檢查 PR
gh --no-pager pr view <branch-name> --json number,title,url,state

如果沒有 PR，通知使用者，並提議使用 create-pr 技能建立一個。

2. 檢查 CI 狀態

取得所有 CI 檢查的狀態：

gh pr view <branch-name> --json statusCheckRollup

解析輸出，識別：

• 已完成與進行中的檢查
• 成功的檢查
• 失敗的檢查及其名稱與詳細資訊 URL

如果 CI 仍在執行中，通知使用者哪些檢查已失敗或通過，標示仍在執行的檢查，並建議等待完成後再進行診斷。

3. 提取失敗日誌

對於每個失敗的檢查，使用狀態檢查中的 run ID 提取日誌：

gh run view <run-id> --log-failed

重點提取：

• 錯誤訊息及其位置（檔案路徑、行號）
• 編譯錯誤（未使用的匯入、型別不符等）
• Linting/clippy 錯誤及具體的 lint 名稱
• 測試失敗訊息與堆疊追蹤
• 建置失敗及其根本原因

4. 分類錯誤

依類型分組錯誤：

• 格式化問題：cargo fmt 失敗
• Linting 問題：cargo clippy 警告/錯誤
• 編譯錯誤：型別錯誤、缺少匯入、簽章不符
• 測試失敗：失敗的測試及其名稱與失敗原因
• 平台特定問題：WASM、Linux、macOS、Windows 特定失敗

5. 生成修復計畫

使用 create_plan 工具建立計畫文件，包含：

• 問題陳述：失敗檢查的摘要
• 目前狀態：發現的錯誤及其位置
• 建議變更：每個錯誤類別所需的具體修復
• 驗證步驟：用於驗證修復的命令（fmt、clippy、測試、presubmit）

計畫應參考 fix-errors 技能，以取得解決特定錯誤類型的詳細指引。

重要注意事項

• 務必先建立計畫：切勿直接修改程式碼。生成計畫供使用者審查
• 檢查 CI 中的測試狀態：即使測試在本機失敗，也請確認它們在 CI 中通過後再標記為問題
• 不相關的測試失敗：如果測試在 CI 中通過但在本機失敗，可能是環境特定或間歇性問題
• 多種錯誤類型：一次修復一個類別（例如，先修復所有 clippy 錯誤，再處理測試）
• 交叉參考 fix-errors 技能：如需詳細的錯誤解決策略，請使用 fix-errors 技能

常見 CI 檢查名稱

• Formatting + Clippy (MacOS)
• Formatting + Clippy (Linux)
• Run MacOS tests
• Run Linux tests
• Run Windows tests
• Check CI results（摘要檢查）
• WASM build

範例命令

取得 PR 狀態與詳細資訊：

gh --no-pager pr view --json number,title,state,statusCheckRollup

取得特定失敗執行的日誌：

gh run view 12345678 --log-failed

在日誌中搜尋特定錯誤：

gh run view 12345678 --log-failed 2>&1 | grep -A 5 "error:"