diagnose-ci-failure

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番号>
# もしくは詳細（conclusion / detailsUrl）まで見たいとき
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. 修正して検証する

1. 修正方針を決めたら、まず「確認なしで直してよいか、人の判断を仰ぐか」の基準に照らす。
2. 確認なしで直してよい場合 → 最小の修正を当てる。フレーキーは握りつぶさず （sleep 追加やリトライで隠さず）、根本の環境差に対処する。
3. 確認を取るべき場合 → 修正を先に適用せず、まず判断を仰ぐ。

   • 対話モード: 原因・提案する変更・想定される影響をチャットに提示し、承認を待つ。 承認が得られたら実行、得られなければその箇所は保留にして次に進む。

   • --non-interactive モード: 同じ内容を以下のフォーマットで gh pr comment <PR番号> --body によりPRへ投稿し、その箇所は自動修正せず中断する。他に確認不要な箇所があれば続けて対応する。

     ## CI失敗: <失敗したジョブ/チェック名>
     
     **原因の推定**: <ログから読み取った原因>
     **提案する修正**: <具体的な変更内容>
     **人の判断が必要な理由**: <仕様変更/ルール是非/破壊的変更など、該当する理由>
     

     投稿bodyには余計なフッター（参考URLやボット署名など）を追加しない。上記フォーマットのみを 投稿する。

4. 修正を適用した箇所について、対象テスト/チェックを名指し実行して緑を確認する。
5. 変更したファイル全体の Lint を通す（部分修正で別の指摘を増やしていないか）。
6. コミット → push。pre-commit フックがあるプロジェクトでは commit 時に lint/format が走るので、 その結果も確認する。

push 後の CI 結果はここでは待たない。再び失敗したら、その時点でこのスキルを再度最初から実行すればよい （push のたびに CI 完了を待つと 1 サイクルが長くなり、待機中に他の作業も進められない）。

進め方の指針

1. 分類してから動く — 決定的バグ・フレーキー・Lint で直し方が違う。分類を誤ると効かない修正を入れる。
2. ログは核心まで絞る — ノイズに埋もれた expected/got を正確に読むまで、修正方針を決めない。
3. ローカル再現を先に — 再現できれば RED→GREEN で確実に直せる。再現しないならフレーキーを疑う。
4. フレーキーは原因に当てる — リトライや待機で緑にするのは再発の先送り。環境差の本体を直す。
5. push 後の CI 完了は待たない — 再び失敗したら、その時点でこのスキルを再実行する。
6. 判断が要る修正は独断で進めない — 対話モードなら確認、--non-interactive ならPRコメントで 人に委ね、機械的に一意に決まる修正だけを自走で進める。