fusion-github-review-resolution

GitHub のレビューコメントを解決する

使用するタイミング

プルリクエストに未解決のインラインレビューコメントがあり、再現可能で監査可能な解決ワークフローが必要な場合に、このスキルを使用します。

一般的なトリガー（以下すべてでスキルが有効になります）：

URL パターン — すぐに有効化：

• https://github.com/<owner>/<repo>/pull/<number>#pullrequestreview-<id>
• https://github.com/<owner>/<repo>/pull/<number>（コンテキストからレビュー作業が必要だと判断できる場合）

ユーザーからの明示的なリクエスト：

• 「レビューコメントを修正して」
• 「この PR のレビューのフィードバックに対応して」
• 「未解決のレビューコメントがあります。修正してください」
• 「この PR のスレッドを解決して」
• 「この PR の未解決コメントをすべて処理して」
• 「レビューコメントごとに、修正、テスト、コミット、返信、解決をして」
• 「未解決のレビュー スレッドを閉じて」
• 「このレビューを確認し、修正したらスレッドを解決して」
• 「未対応のレビューのフィードバックを解決して」
• 「この PR で変更を求められています。修正してください」

暗黙的なトリガー／エージェントによる検出：

• エージェントに PR の作業を依頼されたが、その PR が「変更を要求」の状態になっている
• PR に未解決のレビュースレッドがあり、ユーザーが PR の改善またはマージを依頼している
• PR の作業中に、エージェントが未解決のレビュー会話を検出した

使用しないタイミング

• 未解決のレビューコメントがない
• リクエストが、コード変更を伴わないフィードバックの要約または説明のみである
• 対象のスレッドがすでに解決済み、または古く、対応済みである
• ブランチ／ワークツリーが意図的に読み取り専用になっている

必要な入力

実行前に収集します：

• リポジトリのオーナー／名前
• プルリクエスト番号または URL
• コメントの対象を絞るための任意のレビュー ID（例：pullrequestreview-<id>）
• ブランチ／ワークツリーに関する判断（現在のチェックアウトがすでに PR のヘッドブランチ上にある場合は質問を省略します。「手順 1」を参照）
• リポジトリで必要な検証コマンド

レビュー URL が指定されている場合（github.com/<owner>/<repo>/pull/<number>#pullrequestreview-<id>）、 URL からオーナー、リポジトリ、PR 番号、レビュー ID を自動的に抽出します。 確認が必要なのは、ブランチ／ワークツリーの選択と検証コマンドのみです。

任意：

• 関連する Issue の参照（例：equinor/fusion-core-tasks#432）
• 複数のコメントが同じファイルに関係する場合のコミット単位の希望

手順

ユーザーが明示的に異なる順序を求めない限り、次のフェーズ順に従います：取得 → 分析 → 修正 → 検証 → プッシュ → 返信 → 解決 → 確認。コード編集の再試行と GitHub スレッドの変更を交互に行わないでください。

1. ブランチ／ワークツリーの状況を確認する

   • まず現在のチェックアウトのブランチが PR のヘッドブランチと一致するか確認します。
   • 現在のブランチがすでに PR のヘッドブランチと一致している場合は、そのまま作業を進めます。ワークツリーについて質問しないでください。
   • それ以外の場合（現在のブランチが異なる場合、またはワークスペースが main／master のような共有ブランチ／長期運用ブランチ上にある場合）は、他のワークフローに関する質問をする前に、専用の git ワークツリーを使用するかどうかを尋ねます。
   • 使用する場合は、ワークツリーを使用または作成し、その中で作業を続けます。

2. 未解決のコメントを収集し、作業用トラッカーを作成する

   • #pullrequestreview-<id> を含むレビュー URL が指定されている場合は、取得する前に URL からオーナー、リポジトリ、PR 番号、レビュー ID を解析します。
   • assets/review-resolution-checklist.md をコピーするか開いてください。これが作業用ドキュメントになります。 コンテキストセクションに記入し、各スレッドを確認しながらコメント追跡テーブルを更新します。
   • PR のレビュー スレッドを取得し、未解決のスレッドを絞り込みます。
   • 特定のレビュー ID またはレビュー URL が指定されている場合は、そのレビューのコメントに限定します。
   • 対象のレビュー内では、そのレビュー ID に関連するコメントをすべて収集します（明示的に要求されていない限り、他のレビューからの返信は含めません）。
   • 次の情報を含む作業用リストを作成します。スレッド ID、コメント ID、親レビュー ID、ファイルパス、元のコメント本文、およびそのスレッド内の後続の返信すべて（コントリビューターからの返信を含む）。
   • 各スレッドの返信チェーン全体を確認します。コメントの解決方法を判断する際に考慮すべき補足説明、制約、追加の背景情報がコントリビューターから追加されている場合があります。
   • GitHub を変更する前に、対象スレッド ID のベースライン一覧と未解決スレッド数を記録します。

3. 各コメントを理解し、調査して判断する

   • 該当するファイルと周辺のロジックを読みます。
   • 現在のコード、要件、周辺のコンテキストに照らして、フィードバックが正しい、一部正しい、古くなっている、または誤っているのいずれかを判断します。
   • レビュアーの指摘が常に正しいとは限りません。古い、または誤ったコメントに従うためだけに、コードを不必要に変更しないでください。
   • フィードバックが正しい場合は、根本原因を確認し、安全に対応できる最小限の修正を特定します。
   • フィードバックが明らかに誤っている、または古くなっている場合は、不必要なコード変更を行う代わりに、簡潔で根拠に基づく返信を準備します。
   • 判断に確信が持てない場合は、編集する前に関連するテストや使用箇所を確認します。
   • ローカルで調査しても疑問が残る場合は、コードを変更したりレビュー スレッドに変更を加えたりする前に、ユーザーに確認します。

4. 修正、確認、コミット（コメントごと）

   • 妥当または一部妥当と判断したコメントに対してのみ、対象を絞ったコードやドキュメントの変更を適用します。
   • まず対象を絞ったチェックを実行し、その後、リポジトリで必要とされるチェックを実行します。
   • 可能であれば、コメントごとに 1 つのコミットを作成します。
   • 2 つのコメントに分割できない変更が必要な場合は、1 つのコミットを作成し、返信で両方のコメントをそのコミットに関連付けます。
   • 対応しないコメントについては、最終的な返信を明確かつ監査可能にするため、理由をトラッカーに記録します。

5. すべての修正後に一度だけプッシュする

   • コメントに関連するすべてのコミットを作成した後、ブランチの更新を一度だけプッシュします。

6. 各レビューコメントに返信し、解決済みにする

   • スレッドを変更する前に、次の順序で構造化ツールを優先してください。
     1. 現在のクライアントセッションで利用できる、専用の GitHub MCP レビュー スレッド返信／解決ツール
     2. バンドルされている GraphQL アセット、またはバンドルされている scripts/resolve-review-comments.sh
     3. 一時的な Python スクリプト、単発の一括処理ヘルパー、または無条件に gh api を繰り返す処理は使用しないでください。
   • 投稿する前に、チェックリスト／トラッカーに基づいて、対象スレッドごとに返信文を1つだけ用意してください。
   • 返信／解決の試行でエラー、タイムアウト、または不確かな結果が返された場合、再試行する前に現在のスレッド状態を再取得してください。
   • 各スレッドでは、ユーザーの入力待ちでスレッドがまだ不確かな場合を除き、次の2つの手順をこの順序で続けて行う必要があります。
     1. スレッドに返信を投稿します。変更内容とコミットハッシュを記載するか、コメントが誤りまたは古いためコードを変更しなかった理由を説明してください。
     2. 返信の投稿直後にスレッドを解決済みにします。先に解決してはいけません。
   • 1回の実行につき、各スレッドへの返信の試行は最大1回です。
   • 同等のエージェント作成の返信がすでにある場合、別の返信は投稿せず、それを再利用し、スレッドが未解決の場合にのみ解決してください。
   • 異なるエージェント作成の返信がすでにある場合、別のコメントを重ねて投稿せず、停止して手動で確認してください。
   • スレッドがまだ不確かな場合は解決しないでください。まずユーザーに確認を求めてください。
   • 返信せずにスレッドを解決してはいけません。返信を投稿した後にスレッドを解決しないままにしてはいけません。
   • 返信は具体的にしてください。「修正しました」だけではなく、変更したファイル／行とコミットを明記してください。

7. クローズ状態を確認する

   • レビュースレッドを再確認し、対象の未解決スレッドが残っていないことを確認してください。
   • 対象の未解決スレッド数がゼロになったこと、および今回の実行中にエージェントの返信が重複して作成されていないことを確認してください。
   • ワークフローで成功が求められる場合は、最新の CI ステータスを再確認してください。

8. 元のレビュー作成者に新たなレビューを依頼するか確認する

   • 修正をプッシュしてスレッドを解決した後、レビューコメントの作成者に新たなレビューを依頼するか、ユーザーに確認してください。
   • 依頼する場合は、そのレビュアーのユーザー名を指定してレビューを依頼し、依頼を送信したことを報告してください。

9. スクリプトによる実行（任意）

   • scripts/get-review-comments.sh を使用して、一致するレビューコメント（レビュー ID に関連付けられたサブコメントを含む）を取得できます。
   • 結果は、最初の100件のレビュースレッドと、各スレッドの最初の100件のコメントに制限されます。
   • テストの例：
     • skills/.experimental/fusion-github-review-resolution/scripts/get-review-comments.sh --owner equinor --repo fusion-skills --pr 27 --review-id 3837647674
   • 古い一致スレッドのコメントが必要な場合は、--include-outdated を使用してください。
   • scripts/resolve-review-comments.sh を使用すると、重複返信を防ぐチェックを含め、ドライランを先に行ってから、一致するスレッドに返信して解決できます。
   • デフォルトのドライラン動作を維持し、--apply は修正をコミットしてプッシュした後にのみ使用してください。
   • デフォルトでは、スレッドにすでに認証済みユーザーの返信が含まれている場合、スクリプトは返信の追加を拒否します。手動で確認した後に限り、--allow-additional-reply を使用してください。
   • ドライランの例：
     • skills/.experimental/fusion-github-review-resolution/scripts/resolve-review-comments.sh --owner equinor --repo fusion-skills --pr 27 --review-id 3837647674 --include-resolved
   • 適用の例：
     • skills/.experimental/fusion-github-review-resolution/scripts/resolve-review-comments.sh --owner equinor --repo fusion-skills --pr 27 --review-id 3837647674 --apply --message "Addressed in <commit>: <what changed>."

ツールの使い分け（MCP と GraphQL）

高レベルな PR 操作や、現在のクライアントが提供する専用のレビュー スレッド変更操作には、GitHub MCP ツールを使用します。MCP の対応範囲が不足している場合は、スレッド単位のレビュー操作に GraphQL を使用します。

ワークフローの操作	優先するツール	備考
レビュアーを依頼／PR メタデータを更新	mcp_github_update_pull_request	コラボレーターのレビュアーと標準的な PR 更新に対応します。
PR レビューを作成または送信	mcp_github_pull_request_review_write	保留中のレビューのライフサイクル操作を処理します。
PR に一般的なコメントを追加	mcp_github_add_issue_comment	PR の会話に Issue 形式のコメントを追加します。インラインのスレッド返信ではありません。
レビュー スレッドとコメントを一覧表示	assets/pull-request-review-threads.graphql	スレッド単位のコンテキストを取得するには、gh api graphql -f query=@assets/pull-request-review-threads.graphql と組み合わせて使用します。
特定のレビュー ID の未解決スレッド数を取得	assets/unresolved-thread-count-for-review.graphql	レスポンスを後処理し（例：jq）、レビュー ID と未解決状態で絞り込みます。
レビュー スレッドに返信	Dedicated MCP review-thread reply tool、それ以外の場合は assets/add-pull-request-review-thread-reply.graphql	利用可能な場合は MCP ツールを優先します。それ以外の場合は、その場しのぎのスクリプトではなく、同梱のスレッド専用ミューテーションを使用します。
レビュー スレッドを解決	Dedicated MCP review-thread resolve tool、それ以外の場合は assets/resolve-review-thread.graphql	現在のクライアント／セッションに対応する構造化ツールを使用します。⚠️ GraphQL に関する注意：resolveReviewThread が使用するのは pullRequestReviewThreadId ではなく threadId です。
PR レビューを一覧表示（レビュー URL／ID の検索に対応）	assets/pull-request-reviews.graphql	レビュー URL のコンテキストから作業を開始する場合に便利です。

ヒント： 完全なミューテーション／クエリの構文とパラメーター名については、assets 内の各 .graphql ファイルを参照してください。

GraphQL のコストに関する注意

レビュー解決ワークフローでは、複数の GraphQL ミューテーション呼び出し（スレッドごとに返信＋解決）が行われます。慎重に実行してください。

• ミューテーションのコストは、それぞれセカンダリレート制限のポイントを 5 消費します（読み取りクエリは 1）。処理するスレッド数に応じて予算を見積もってください。
• セカンダリレート制限を回避するため、連続するミューテーション呼び出しの間は少なくとも 1 秒待機してください。
• first／last のコネクション引数は小さく保ってください（1 ページですべてのスレッドが必要な場合に限り、first: 100 を優先します）。
• セカンダリレート制限エラーまたは retry-after ヘッダーが返された場合は処理を停止し、再試行する前に指定された待機時間を守ってください。
• クライアントが専用の MCP レビュー スレッドツールを提供している場合は、常に生の GraphQL よりもそちらを優先してください。

トークン予算の指針

• スレッドの一覧は一度だけ取得し、すべてのスレッド単位の作業で再利用してください。返信と解決の間にスレッドを再取得しないでください。
• 予算の目安：未解決スレッドが N 件ある場合、一覧取得 1 回＋返信ミューテーション N 回＋解決ミューテーション N 回、合計 1 + 2N 回の呼び出しが見込まれます。10 件のスレッドがあるレビューでは約 21 回の呼び出しが必要です。
• スレッド数が 15 件を超える場合は、ミューテーションを開始する前にレート制限のリスクをユーザーに警告し、少数のグループに分けて処理することを提案してください。
• 最初の取得で得た PR メタデータ（タイトル、ブランチ、CI の状態、変更ファイル）をキャッシュし、コミットメッセージと返信に再利用してください。
• 手順の間に PR レベルの読み取りを重複して行わないでください。1 回の解決処理中にデータが変わることはありません。

想定される出力

次の内容を含む簡潔なレポートを返してください。

• 処理したコメント数
• 対応の概要（修正、理由を添えて対応を見送り、ユーザーにエスカレーション）
• 変更したファイル
• コミット一覧（ハッシュ＋メッセージ）
• 実行した検証コマンドと結果
• プッシュしたことの確認
• スレッドごとの返信／解決の確認
• 完了したチェックリストの場所
• 残っている未解決スレッドまたはブロッカー

関連 Issue の使用

Issue が指定されている場合（例：equinor/fusion-core-tasks#432）：

• 進捗報告／最終報告で Issue に言及してください。
• 実装を Issue の範囲に沿わせてください。
• 無関係な PR 自動化に範囲を広げないでください。

安全性と制約

• このスキルは変更を加えることができます。リポジトリ内のワークフロー指示がインラインのガイダンスと矛盾する場合は、リポジトリ内の指示を優先してください。
• ログや返信でシークレットやトークンを決して公開しないでください。
• シェルに埋め込んだコマンド文字列より、argv ベースのプロセス実行を優先してください。
• 差分は最小限にし、レビューのフィードバックに関係する範囲に限定してください。
• レビューのフィードバックが正しいと決めつけず、まずコードと要件に照らして検討してください。
• 調査してもコメントの意味が曖昧なままなら、推測せずにユーザーに尋ねてください。
• 具体的な修正内容を返信に投稿せずに、スレッドを解決しないでください。
• コマンドを実際に実行していない限り、チェックに合格したと主張しないでください。
• 強制プッシュは行わず、通常のコミットを作成し、すべての修正後に一度だけプッシュしてください。
• コメントが古くなっていても未解決の場合は、次のいずれかを行ってください。
  • 明確な説明とコミット参照を添えて解決する。
  • 未解決のままにし、その理由を報告する。
• スクリプトモードではデフォルトのドライラン動作を維持し、変更には明示的な --apply を必須としてください。