| name | diagnose-ci-failure |
| description | GitHub Actions の CI 失敗を、失敗ジョブの特定 → ログからの原因抽出 → 原因分類 → ローカル再現 → 修正 → 検証まで体系的に進めるスキル。特に、失敗ログのノイズに埋もれて原因が見えないとき、環境依存でフレーキーに落ちているときに役立つ。修正に人の判断が必要な場合は、対話モードでは確認して中断し、--non-interactive 指定時はPRにコメントを投稿して中断する。 |
| license | MIT |
| disable-model-invocation | true |
| argument-hint | [PR番号] [--non-interactive] |
CI失敗の調査〜修正フロー
CI が落ちたときは、闇雲にコードをいじる前に 「失敗ジョブを特定 → ログの核心を掴む →
原因を分類 → ローカル再現 → 修正 → 検証」 の順で進める。特に効くのは 2 点:
- 失敗ログは大量のノイズ（セットアップ・依存関係の取得）に埋もれるので、核心行だけに絞る
- 原因の種類によって直し方が変わる（決定的なバグとフレーキーとLintでは対処が別物）ので、
手を動かす前に分類する
以下はプロジェクトに依存しない汎用フロー。具体のテスト実行コマンドや pre-commit の仕組みは
対象リポジトリの慣習（README / bin/ / lint 設定）に合わせて読み替える。
実行モード
修正の中には、機械的に直せず人の判断が要るものがある（詳細は後述）。判断が要る箇所に
当たったときの止まり方は、実行モードで変える。
- 対話モード（デフォルト）: チャットでユーザーに確認を提示し、その箇所の処理を中断する。
--non-interactive 指定時: CI/GitHub Actions など、ユーザーが即答できない環境を想定。
gh pr comment <PR番号> で確認事項をPRに投稿し、その箇所の処理を中断する。他に自動修正できる
箇所があれば、そちらは続行してよい。
モードは環境変数などで自動判定しない（claude -p かどうかをスキル側から確実に判定する手段は
ない）。呼び出し側が --non-interactive フラグで明示的に宣言する。
1. 失敗ジョブを特定する
PR のどのチェックが落ちているかを掴む。
gh pr checks <PR番号>
gh pr view <PR番号> --json statusCheckRollup
conclusion が FAILURE のジョブ名と、その detailsUrl（末尾が .../job/<jobId>）を控える。
SKIPPED や SUCCESS は無視してよい。複数落ちている場合は、後続の派生失敗ではなく
最初に落ちた根本のジョブ（テスト本体・ビルド等）から見る。
2. 失敗ログを核心まで絞る（勘所）
gh run view --job <jobId> --log-failed は、失敗ステップだけでなく ランナーのセットアップ・
依存関係のダウンロード・イメージ取得のログまで大量に含む。そのまま眺めると核心が埋もれる。
grep で失敗の核心行だけに絞り込む:
gh run view --job <jobId> --log-failed \
| grep -iE "fail|error|expected|assert|✗|✘" \
| grep -viE "download|install|fetch|cache|pulling|waiting"
抽出・除外のキーワードは一例。対象リポジトリの実際のログの語彙（テストランナーやツールの
出力形式）に合わせてキーワードを足し引きする。核心行として拾うべきなのは種類を問わず次の情報:
- 失敗の主張: 期待値と実際の値、アサーション失敗メッセージ
- 発生箇所: ファイルパス:行番号
- 再現用コマンド: 多くのテストランナーは失敗時に単体再現コマンドを出力する
- Linter/静的解析の場合: 指摘ルール名と該当箇所
失敗が 1 件なら、その期待値/実際の値と発生箇所を正確に読む。ここを曖昧にしたまま直しにいかない。
3. 原因を分類する
種類で対処が変わるので、手を動かす前にどれかを確定する。
| 種類 | 兆候 | 対処の方向 |
|---|
| テスト失敗（決定的） | 毎回同じ expected/got。ローカルでも同様に落ちる | プロダクション or テストのバグ。ローカル再現して直す |
| フレーキー（環境依存） | ローカルは緑・CIは赤、実行や再実行で結果が揺れる | 環境差（OS/DB/TZ/実行順/時刻精度）を疑う → references/flaky-pitfalls.md |
| Lint / Formatter | Linter/Formatter の規約違反指摘 | 多くは自動修正（autofix）で解消。ただしルール自体の是非も一応検討 |
| 静的解析 / 型 / セキュリティ | 静的解析・型チェッカー・セキュリティスキャナの警告 | 指摘箇所を修正、または正当な理由付きで抑制 |
| 環境・インフラ | セットアップ/ネットワーク/依存取得の失敗。コードと無関係 | コード起因でないので再実行、または CI 設定側を見る |
判別に迷うときは、同じジョブを再実行して結果が変わるかを見る。変わるならフレーキー、
変わらないなら決定的。
確認なしで直してよいか、人の判断を仰ぐか
修正に着手する前に、この分類とは別にもう一段判定する。
- 確認なしで直してよい: Lint の自動修正（autofix）、期待値と実装のズレが一意に定まる明白な
バグ、環境起因での再実行。
- 確認を取るべき: プロダクションの仕様・挙動を変える修正、Lint/静的解析のルール自体の是非
（ルールを変える・抑制する判断）、フレーキーの根本対処で設計変更を伴うもの、テスト期待値の変更
が仕様変更を意味する場合、その他の破壊的変更全般。
迷ったときは「機械的に一意に決まる修正か」を基準にする。決まらない・複数の妥当な選択肢がある
場合は確認を取る側に倒す。
4. ローカルで再現する
該当チェックだけを名指しでローカル実行する（全体を回すと遅く、ノイズも増える）。
- テスト: 失敗した
ファイル:行 や example 名を指定して 1 ケースだけ走らせる。
- Lint: 対象ファイルだけを指定して走らせる。
ローカルで再現しない場合は、フレーキー（環境依存）を強く疑う。「ローカルは緑・CIは赤」は
コードのバグではなく、OS・DB・タイムゾーン・実行順・時刻精度などの環境差が原因のことが多い。
その場合は references/flaky-pitfalls.md の典型パターンと突き合わせる。
バグ修正は RED → GREEN で進める。先に「修正前のコードで意図通り落ちる（RED）」ことをローカルで
確認してから直す。RED を飛ばすと、その修正が本当に原因に効いているか検証できない。
5. 修正して検証する
- 修正方針を決めたら、まず「確認なしで直してよいか、人の判断を仰ぐか」の基準に照らす。
- 確認なしで直してよい場合 → 最小の修正を当てる。フレーキーは握りつぶさず
（
sleep 追加やリトライで隠さず）、根本の環境差に対処する。
- 確認を取るべき場合 → 修正を先に適用せず、まず判断を仰ぐ。
-
対話モード: 原因・提案する変更・想定される影響をチャットに提示し、承認を待つ。
承認が得られたら実行、得られなければその箇所は保留にして次に進む。
-
--non-interactive モード: 同じ内容を以下のフォーマットで gh pr comment <PR番号> --body
によりPRへ投稿し、その箇所は自動修正せず中断する。他に確認不要な箇所があれば続けて対応する。
## CI失敗: <失敗したジョブ/チェック名>
**原因の推定**: <ログから読み取った原因>
**提案する修正**: <具体的な変更内容>
**人の判断が必要な理由**: <仕様変更/ルール是非/破壊的変更など、該当する理由>
投稿bodyには余計なフッター（参考URLやボット署名など）を追加しない。上記フォーマットのみを
投稿する。
- 修正を適用した箇所について、対象テスト/チェックを名指し実行して緑を確認する。
- 変更したファイル全体の Lint を通す（部分修正で別の指摘を増やしていないか）。
- コミット → push。pre-commit フックがあるプロジェクトでは commit 時に lint/format が走るので、
その結果も確認する。
push 後の CI 結果はここでは待たない。再び失敗したら、その時点でこのスキルを再度最初から実行すればよい
（push のたびに CI 完了を待つと 1 サイクルが長くなり、待機中に他の作業も進められない）。
進め方の指針
- 分類してから動く — 決定的バグ・フレーキー・Lint で直し方が違う。分類を誤ると効かない修正を入れる。
- ログは核心まで絞る — ノイズに埋もれた
expected/got を正確に読むまで、修正方針を決めない。
- ローカル再現を先に — 再現できれば RED→GREEN で確実に直せる。再現しないならフレーキーを疑う。
- フレーキーは原因に当てる — リトライや待機で緑にするのは再発の先送り。環境差の本体を直す。
- push 後の CI 完了は待たない — 再び失敗したら、その時点でこのスキルを再実行する。
- 判断が要る修正は独断で進めない — 対話モードなら確認、
--non-interactive ならPRコメントで
人に委ね、機械的に一意に決まる修正だけを自走で進める。
