review-prs

PR をレビューする

プルリクエストをレビューし、それぞれにインラインコメントで指摘事項を残します。修正方法が明確な場合は、作成者がワンクリックで適用できるよう、修正案も添えます。各プルリクエストは2段階で確認します。意図された課題の要件を満たしているか、そしてコードが正しいかを確認します。

修正案の提示は GitHub の機能なので、このスキルには GitHub リポジトリと gh が必要です。課題トラッカーは GitHub、Jira、ローカルの Markdown のいずれでもかまいません。

このスキルで指定するのは「レビュー担当者をディスパッチする」のようなアクションであり、ツールではありません。ご利用のプラットフォームで同等の機能を使用してください。

ステージ 1 — プルリクエストを選ぶ

1. gh がインストールされており、gh auth status が成功することを確認します。そうでない場合は理由を伝えて終了します。
2. リポジトリ：ユーザーが指定したものを使用します。指定がない場合は、このチェックアウトの GitHub リポジトリ（gh repo view --json nameWithOwner）を使用します。どちらを使用したか伝えます。
3. プルリクエスト：ユーザーが指定したものを使用します。「すべて」または「オープン中のもの」の場合は、gh pr list --repo <owner/repo> --state open --limit 1000 --json number,title,url,isDraft を実行します。指定された場合を除き、ドラフトは除外します。
4. 一覧を表示し、それぞれのプルリクエストにコメントとして指摘事項を投稿することを伝えます。ユーザーが一覧を承認した時点で、投稿の許可を得たものとします。ただし、すでに許可を得てディスパッチされている場合は除きます。たとえば implement-issues では、作成したドラフトに対してすでに許可を得ています。その場合は一覧を表示して続行します。

ステージ 2 — 各プルリクエストのコンテキストを集める

1. gh pr view <number> --json title,body,baseRefName,headRefOid で説明と HEAD コミットを取得します。ローカルでレビューできるよう、コミットを取得します。git fetch origin pull/<number>/head <base> を実行し、次に HEAD_SHA を HEAD コミットに設定し、BASE_SHA を git merge-base origin/<base> <HEAD_SHA> に設定します。
2. 関連する意図の課題を探します。タイトルと本文で、docs/agents/issue-tracker.md の Linking セクションに記載された参照形式を確認します。GitHub の場合は Closes #<number> または Relates to #<number> です。Reading method を使って課題を読みます。関連する課題がない場合、またはトラッカー設定がない場合は、そのプルリクエストの意図レビューを省略し、レビューでその旨を伝えます。
3. すでに投稿されているコメントを確認します。gh api --paginate repos/<owner>/<repo>/pulls/<number>/comments を実行し、すでに指摘されている内容を重複して投稿しないようにします。

ステージ 3 — レビュー

意図の確認（あなた）。 差分を課題の Proposed outcome と Constraints に照らし合わせます。課題が求めているのにプルリクエストで実現されていないこと、課題で求められていないのにプルリクエストで実装されていること、そして差分が違反しているすべての Constraints を報告します。

コードの確認（レビュー担当者）。 Superpowers の requesting-code-review を使用します。コードレビュー担当者をディスパッチし、プルリクエストのタイトルと説明を説明として、意図の課題を要件として指定します。意図の課題がない場合は、プルリクエストの本文を要件として指定します。さらに BASE_SHA と HEAD_SHA も指定します。プラットフォームで利用可能な最も高性能なモデルでディスパッチします。ただし、docs/agents/delivery.md が存在し、そこで pr-code-reviewer の役割に割り当てられたモデルが、このプラットフォームのディスパッチで受け付けられる場合は、そのモデルを使用します。使用できるのは、このプラットフォームの Tiers テーブルで照合したティア、または正確なモデル名です。そのモデルを使用してください。役割が定義されていない場合、またはモデルを特定できない場合は、最も高性能なモデルを使用し、その旨をレポートで伝えます。そこで止めてはいけません。レビューでは何も変更しないため、複数のプルリクエストのレビュー担当者を同時にディスパッチします。サブエージェントをサポートしていない場合は、各差分を自分でレビューします。

意図のみのレビュー。 コードの確認を省略するようディスパッチされた場合は、コードの確認を省略します。implement-issues は、高負荷の作業より下ではこのようにします。ビルドがすでにブランチ全体のコードレビューを終えているためです。レビュー本文に、確認を省略したこととその理由を記載します。

投稿前にすべての指摘を確認する。 各指摘が示すコードを開き、その指摘が妥当であることを確認します。レビュー担当者が誤っていることもあります。誤ったコメントは、見落としよりも作成者に大きな負担をかけます。妥当でない指摘は除外し、除外した理由をレポートに記載します。

ステージ 4 — 変更案をコメントする

各プルリクエストにつき、event: "COMMENT" としてレビューを 1 件投稿します。

• 各指摘は、対象となる変更行に紐付けます。path、line、side: "RIGHT" を指定し、複数行にまたがる場合は start_line と start_side も指定します。GitHub が受け付けるのは、プルリクエストの差分に含まれる行のみです。

• 各コメントは重要度（Critical、Important、Minor）で始め、その影響を 1 文で説明します。

• 修正内容が明確な場合は、コメントの末尾に suggestion ブロックを付け、対象として紐付けた行の完全な新しいテキストを、ファイルと同じインデントで記載します。

  **Important** — an invalid address reaches the queue and fails later in
  the worker, where the user never sees the error.
  
  ```suggestion
  if (!isValidEmail(email)) throw new ValidationError("email");
  await queue.add("confirm", { email });
  ```
  

• 修正に設計上の議論が必要な場合、または差分外の行に関わる場合は、suggestion ブロックを付けずに説明するか、レビュー本文に記載します。

gh api --method POST repos/<owner>/<repo>/pulls/<number>/reviews --input review.json

{
  "commit_id": "<HEAD_SHA>",
  "event": "COMMENT",
  "body": "<counts by severity, and the intent pass's result>",
  "comments": [
    {
      "path": "src/signup.ts",
      "start_line": 41,
      "start_side": "RIGHT",
      "line": 42,
      "side": "RIGHT",
      "body": "<severity and consequence, then the suggestion block>"
    }
  ]
}

指摘がない場合は、インラインコメントなしで、その旨を本文に記載したレビューを 1 件投稿します。

ステージ 5 — 報告

プルリクエスト、関連付けられた Issue、重要度別に投稿した指摘、レビューの URL を記載した表を 1 つ作成します。その後、チェック段階で見送った指摘と、その理由を列挙します。

してはいけないこと

• 承認や変更要求をしないでください。レビューは COMMENT のみで投稿してください。承認するかどうかはユーザーが決定します。
• プルリクエストのブランチにコミットをプッシュしないでください。提案を適用するかどうかは作成者が決定します。
• コードで確認していない指摘を投稿しないでください。
• コメントの対象行数より多い、または少ない行を置き換える提案や、対象行の完全な新しいテキストになっていない提案を書かないでください。
• プルリクエストの差分に含まれない行にコメントを紐付けないでください。
• すでにプルリクエストで指摘されている内容を投稿しないでください。
• コード確認を省略しないでください。コード確認を無効にして割り当てられた場合は、その旨をレビュー本文に記載してください。
• 意図の確認を黙って省略しないでください。関連付けられた Issue がない場合は、その旨をレビュー本文に記載してください。