vk-pr-review

name	vk-pr-review
description	既存の PR を起点に、タイトル・本文・テスト・コード/UX/e2e レビュー・CodeRabbit の状況を横断チェックし、未実施のレビューを補ってマージ可能な状態かを判定する。PR のレビュー（点検）を依頼されたときに使用

/vk-pr-review スキル

前提条件（軟ゲート）: このスキルは、対象リポジトリの owner が許可リスト org.allowed_owners（~/.vk-agents/config.json）に含まれる場合はそのまま、含まれない場合はユーザー確認のうえ使用できます。判定手順は rules/repository-access.md を参照。

既存の PR を起点に、レビュー観点・テスト・各種レビューの実施状況を満たし、マージ可能かを横断点検します。不足レビューはこのスキル内で実施し、最後に結果を PR へサマリーコメントとして投稿します。

このスキルの位置づけ

• vk-kore は issue 起点で「実装 → レビュー → PR → テスト → 報告」を一気通貫で行います。本スキルはそのうち レビュー・点検フェーズ（vk-kore のステップ 4-4 / 4-6 / 4-7 / 4-8）相当を、既存 PR に単体実行できるよう切り出した ものです。
• 作成済み PR（人間が作った PR・別経路で作られた PR を含む）に「レビューして」「点検して」と頼まれたときに使います。
• PR の作成は vk-pr、bot PR の処理は vk-bot-pr の責務であり、本スキルの責務外です。

トリガー

以下の表現を含む場合に使う:

• 「この PR をレビューして」「PR #123 を点検して」
• 「この PR、マージできる状態か確認して」
• 「レビューが一通り済んでいるか見て」

引数

• PR の URL または番号（例: https://github.com/vektor-inc/xxx/pull/123 または #123）
• 番号のみ指定された場合は、カレントディレクトリの gh repo view --json nameWithOwner で <REPO> を補完する
• オプションで wp-env のポート番号を wp-env-port=NNNN 形式で渡せる（e2e で麗美がローカル環境を使う場合の衝突回避用。testsPort は NNNN + 1）

手順

主役はメイン Claude（点検役）です。各レビュー担当（安藤・植草・麗美）は Agent ツール（subagent_type: general-purpose）でサブエージェントとして起動します。メンバーを呼ぶ際は対応する persona.md を Read してから Agent に渡します。

1. PR の取得とリポジトリ確認

1. $ARGUMENTS から PR の URL / 番号を取得し、<REPO>（owner/repo）と <PR>（番号）を確定する

2. rules/repository-access.md のゲート判定を行う（軟ゲート）。owner が許可リストに含まれない場合は「⚠️ 許可リスト外のリポジトリです（オーナー: <オーナー名>）。続行しますか？」と確認し、明示承認された場合のみ続行する

3. PR の基本情報を取得する:

   gh pr view <PR> -R <REPO> --json title,body,headRefOid,commits,comments,reviews,files,state,isDraft,author,labels
   

4. state が MERGED / CLOSED ならその旨を報告して終了する

5. 続行可否の確認: このスキルは最後に点検結果サマリーを PR に投稿するため、先に「いま点検してよい PR か」を確認する。次のいずれかに当てはまる場合は、点検前にユーザーへ「点検を実行し、結果コメントをPRへ投稿してよいですか？」と確認する。確認待ちラベルの有無や Draft 状態は、いま点検してよいかのシグナルとし、明示的な続行承認が得られた場合のみ続行する。

   • labels に 確認待ち / 1人目確認待ち / 2人目確認待ち のいずれも含まれない
   • isDraft が true（Draft 状態の PR）

   上記いずれにも当てはまらない（確認待ちラベルあり かつ 非 Draft）場合は、確認せず続行する。

6. author.login（PR 作成者の GitHub アカウント）と author.is_bot（GitHub が返す bot 判定フラグ）を控える。手順10の通知（メンション）先判定に使う

2. タイトルの点検（change-title.md）

1. rules/change-title.md を Read で読み込む（記憶で判定しない）
2. PR タイトルが分類表記（許可された分類のみ）・対象ブロック名・体言止め・原因→結果・記載言語のルールに沿っているか照合する
3. 違反があれば、具体的な修正案（あるべきタイトル）を控える。修正は「3. ... 」では行わず、最終サマリー（手順10）で指摘・提案する

3. 本文の点検（pull-request.md）と実態との整合

1. rules/pull-request.md を Read で読み込む
2. PR 本文（description）が、確認手順・スクリーンショット・概要などルールの要求を満たすか確認する
3. 本文と変更の実態の整合を確認する（重要）。PR 作成後の修正 push で仕様が変わり、本文が初版のまま実態と乖離する場合がある。
   • gh pr diff <PR> -R <REPO> で実際の差分を取得する
   • 本文に書かれた変更内容・確認手順が、現在の差分の実態と一致するか照合する
   • 乖離（本文が古い・実態に存在しない記述・実態にあるのに本文に無い変更）があれば、その箇所を控える
4. 問題があれば最終サマリー（手順10）で指摘する

4. changelog の点検（changelog.md）

1. rules/changelog.md を Read で読み込む（記載対象ファイル・記載タイミング・更新不要なケース・記載言語・バージョン番号の扱いなどを確認する）
2. rules/changelog.md の「記載対象ファイル」に従い、対象の changelog ファイル（WordPress プラグインなら readme.txt の == Changelog ==、その他は CHANGELOG.md 等）を特定し、差分（手順3で取得）に含まれるか確認する
3. 今回の変更が changelog 記載を要するか判断する。rules/changelog.md の「更新不要なケース」（ワークフロー設定・開発環境設定・未リリース機能の不具合修正など）に該当する場合は記載不要とみなす
4. 記載が必要なのに追記が無い、または追記内容が rules/changelog.md / rules/change-title.md のルール（分類・体言止め・記載言語・バージョン番号を書かない・プレースホルダーを書かない等）に沿っていない場合は、その箇所を控える
5. 問題があれば最終サマリー（手順10）で指摘する

5. コーディングルールの点検（coding-rules.md）

1. 差分に PHP・JS などプログラムファイルの変更が含まれる場合、rules/coding-rules.md を Read で読み込む（記憶で判定しない）
2. 追加・変更されたコードが coding-rules.md のルールに沿うか照合する。特に コメントの記載言語（coding-rules.md の「コメント言語」）は見落とされやすいため必ず確認する:
   • 対象プロジェクトの readme.txt の有無・言語から記載言語を判定する（判定基準は coding-rules.md を唯一の正とする）。WordPress プラグインなら差分やリポジトリ直下の readme.txt を確認する
   • 日本語のみと判定されるプロジェクト（readme.txt が無い／changelog に日本語が含まれる）で、追加・変更されたコメントに 英語が併記されていないか を確認する。逆に英日併記プロジェクトで片方が欠けていないかも確認する
3. 違反があれば最終サマリー（手順10）で指摘する

6. テストの点検（phpunit.md / e2e.md）

1. 差分に PHP の関数・メソッドの追加・変更が含まれる場合、rules/testing/phpunit.md を Read で読み込み、対応する PHPUnit テストの有無とルール適合を確認する
   • テストが無い場合でも、rules/pull-request.md の「PHPUnit テストの確認」にある例外（フック・フィルターのみ等、単体テストになじまない実装／環境制約）に該当するかを判断する
2. e2e テストが差分に含まれる、または e2e の対象となる UI 変更がある場合、rules/testing/e2e.md を Read で読み込み、テストがルールに沿って書かれているか確認する
3. 不足・ルール違反があれば最終サマリー（手順10）で指摘する

7. レビュー実施状況の判定（最後のコード改変との前後関係）

各レビュー（コード=安藤・UX=植草・e2e=麗美）が、PR 内の最後のコード改変よりも後に実施済みか判定する。古い（最後の push より前の）レビューしか無ければ、改変後のコードがレビューされていないため「未実施」とみなす。

1. 最後のコード改変時刻を取得する:

   gh pr view <PR> -R <REPO> --json commits --jq '.commits[-1].committedDate'
   

2. PR のコメント（手順1で取得済み）から、各レビュアーが投稿したレビュー結果コメントを探す。判別は rules/code-review.md で定められたコメント冒頭のエージェント名表記による（例: 🔍 保（コードレビュー）、🎨 植草（UXレビュー）、🧪 麗美（e2eテスト））
3. 各レビュー種別について、最後のコード改変時刻より後の レビュー結果コメントが存在するかを判定する:
   • 存在し PASS している → 実施済み（再実施不要）
   • 存在しない、または最後の改変より前のコメントしか無い → 未実施（手順8で実施する）

8. 不足レビューの実施

手順7で「未実施」と判定されたレビューを実施する。各レビューの観点・基準はルールファイルを唯一の正とし、ここには複製しない。

• コードレビュー（安藤 / staff-security）: 未実施の場合に実施する。REPO_ROOT/skills/staff-security/persona.md を Read し、Agent（general-purpose）で安藤を起動する。prompt には persona とレビュー対象（<REPO> / <PR> / 差分）を渡す。安藤は rules/code-review.md に基づきセキュリティ・品質・PR 内完結変更への過剰な互換処理をチェックする。出力に「レビュー結果: PASS」が含まれれば通過
• UX レビュー（植草 / staff-ux）: diff に .css / .scss / .jsx / .tsx / .html / PHP テンプレートの変更がある場合に実施する。純粋なロジック変更で UI への影響がない場合は省略可（省略理由を控える）。REPO_ROOT/skills/staff-ux/persona.md を Read して Agent で起動する
• e2e/UI テスト（麗美 / staff-review）: ブラウザでの動作確認対象がある場合に実施する。Skill ツールで staff-review を起動するか、REPO_ROOT/skills/staff-review/persona.md を Read して Agent で起動する。wp-env-port が渡されていれば麗美への依頼に含める。UI 変更がなく確認対象が無い場合は省略可（省略理由を控える）
• 各レビューで問題が見つかった場合は、本スキルの責務（点検）として 指摘をサマリーに記載する。実装の修正が必要な場合は、ユーザーまたは実装担当（和田 / staff-wp-dev）に修正を依頼する（修正→再レビューのループを回すかはユーザー判断に委ねてよい）
• レビュー結果コメントの PR への投稿・エージェント名の明記は rules/code-review.md の「GitHub PR レビュー時のコメント投稿」に従う

9. CodeRabbit レビューの完了確認（coderabbit-monitoring.md）

1. rules/coderabbit-monitoring.md を Read で読み込む（START 取得タイミングの罠があるため記憶で実行しない）。読み込んだ「前提条件」でスキップ判定になった場合は、以下 2-3 の監視ステップを 待機なしでスキップ し、サマリーには同ルールの前提条件に沿って理由を記載してステップ 10 へ進む
2. PR に対する CodeRabbit のレビューが完了しているか（指摘が出尽くし、未対応の指摘が残っていないか）を確認する。要約コメントが Currently processing / review in progress のままでないか、No actionable comments / Actionable comments posted 等の本レビュー特有の文言で完了しているかを rules/coderabbit-monitoring.md の判定手順で確認する
3. 未完了・未対応の指摘がある場合は、その状況をサマリーに記載する。監視ループを回す必要がある場合は rules/coderabbit-monitoring.md の監視フローに従う（Bash の run_in_background を使い Monitor は使わない）

10. レビュー結果サマリーの投稿（必須）

点検結果を1つのサマリーコメントにまとめ、PR に投稿する（gh pr comment <PR> -R <REPO>）。この投稿は省略不可（全項目クリアの場合も、点検済みであることを示すために投稿する）。

サマリーを書く前に、PR の既存議論を最新状態で再取得して総浚いする（必須）。 手順8・9でレビューコメントが新たに投稿されているため、手順1で取得したキャッシュは使わず再取得する。総浚いの取得方法（3経路・--paginate 必須）は rules/coderabbit-monitoring.md の「PR コメントの総浚い（既存議論の全取得）」に従う（--json comments だけだと CodeRabbit の指摘の大半が乗るインラインコメントを取りこぼすため、3経路すべてが必須）。

取得した全コメント・レビューを使い、各指摘が既存議論で言及・議論されていないか照合する。照合結果に応じて次のように扱う:

状態	サマリーへの書き方
既存コメントで議論あり → 解決済み	「既存コメントで対応済み」と明記する
既存コメントで議論あり → 未解決のまま残っている	引き続き指摘として書く。コメント URL を参照先として添える
既存コメントで議論なし	通常どおり指摘する

「既存コメントで対応済み」は省力化の口実にしない（必須）。 CR を含む既存コメントの指摘は、点検が超えるべき "床（最低ライン）" であり、それに乗っかるだけでは CR のラバースタンプになる。照合後、各観点について 「CR の静的解析では拾えない、その観点ならではの指摘が他に無いか」を必ず一度問い直す（セキュリティ文脈・権限/境界、UX 意図・既存ユーザー影響、実フロー・回帰）。重複しない追加観点が見つかればサマリーに足し、本当に無ければ「追加指摘なし（既存コメントを超える所見なし）」と明記する（黙って省略しない）。

書式は rules/decision-record.md に従う（1行目 Comment by vk-agents / 2行目 Status:。作成者が対応すべき指摘があるとき・すべてクリアなときは no-action、ユーザーの判断が必要または担当不明なときは waiting-input）。

要修正・要調整がある場合に誰へメンションして通知するかは、rules/decision-record.md の「通知（メンション）先のルール」に従う（Status の値ではなく「次のアクションを誰が持つか」で決める）。点検結果を次の3つに当てはめる:

• 指摘の解消を PR 作成者が行う場合（タイトル・本文・changelog・コードの修正など、作成者が直せば済むもの）— Status: no-action とし（点検タスク自体は完了しており、通知はメンションが担う）、手順1で控えた author.login を使い、Status: 行の次の行に @<author.login> 以下に要修正・要調整の点があります。ご確認をお願いします 🙏 を記載して、作成者に通知が届くようにする。要対応項目が複数あっても、まとめてこの1行で依頼する（項目ごとに個別メンションはしない）
• 次のアクションがユーザー（点検の実行者）の判断である場合（例: スコープ外の指摘を別 issue に切り出すか、提示した修正案を採るかなど、作成者ではなくユーザーが決めること）— メンションは付けず、Status: waiting-input の記録として残す（ユーザー確認待ちのシグナル）
• PR 作成者が bot（author.is_bot が true。CodeRabbit / dependabot / GitHub App など）、または対応すべき担当が不明な場合 — メンションは付けず、「担当者の確認が必要」として Status: waiting-input の記録を残す（author.login の見た目で bot 判定しない）

すべてクリア（Status: no-action）の場合はメンションを付けない。上記2・3のメンションを伴わないケースは GitHub 通知が誰にも飛ばないため、Status: waiting-input の記録が検知・追跡の役割を担う（オーケストレーター（vk-orchestrator）が監視する前提。記録の投稿は省略不可）。orchestrator が存在しない手動運用（features.task_queue: false かつ headless=1 も無い 等の無人モードでない場合）では waiting-input を拾う者がいないため確認はターミナルで行うが、その場合も記録（コメント投稿）は省略しない。

サマリーには以下を含める:

• 📝 タイトル: ✅ 適合 / ⚠️ 要修正（修正案）
• 📄 本文・実態整合: ✅ 適合 / ⚠️ 乖離あり（箇所）
• 📒 changelog: ✅ 適合 / ⚠️ 不足・要修正（内容）/ ⏭️ 記載不要（理由）
• 🧷 コーディングルール（コメント言語等）: ✅ 適合 / ⚠️ 要修正（箇所・内容）/ ⏭️ 対象外（プログラム変更なし）
• 🧪 テスト（PHPUnit / e2e）: ✅ 適合 / ⚠️ 不足（内容）/ ⏭️ 対象外（理由）
• 🔒 安藤（コードレビュー）: ✅ 実施 PASS / ⚠️ 指摘あり / ⏭️ スキップ（理由）
• 🎨 植草（UX）: ✅ 実施 PASS / ⏭️ スキップ（理由）
• 🧪 麗美（e2e）: ✅ 実施 PASS / ⏭️ スキップ（理由）
• 🐰 CodeRabbit: ✅ 完了・対応済み / ⚠️ 未完了・未対応の指摘あり / ⏭️ スキップ（理由は rules/coderabbit-monitoring.md の前提条件に従って記載）

記述例:

Comment by vk-agents
Status: no-action

**🔍 vk-pr-review（PR 点検）の結果**

**🗂 点検サマリー**

- 📝 タイトル: ✅ 適合
- 📄 本文・実態整合: ✅ 適合
- 📒 changelog: ✅ 適合
- 🧷 コーディングルール（コメント言語等）: ✅ 適合
- 🧪 テスト: ✅ 適合（PHPUnit 追加済み）
- 🔒 安藤（コードレビュー）: ✅ 実施 PASS
- 🎨 植草（UX）: ⏭️ スキップ — 純粋なロジック変更で UI 変更が無いため
- 🧪 麗美（e2e）: ✅ 実施 PASS
- 🐰 CodeRabbit: ✅ 完了・未対応の指摘なし

総評: マージ可能な状態です。

要修正・要調整があり、その解消を PR 作成者が行う場合（作成者をメンションする）の記述例:

Comment by vk-agents
Status: no-action
@octocat 以下に要修正・要調整の点があります。ご確認をお願いします 🙏

**🔍 vk-pr-review（PR 点検）の結果**

**🗂 点検サマリー**

- 📝 タイトル: ⚠️ 要修正 — 分類表記が無いため `[ 不具合修正 ][ ブロック名 ] …` の形にする
- 📄 本文・実態整合: ✅ 適合
- 📒 changelog: ⚠️ 不足 — `readme.txt` の `== Changelog ==` への追記が必要
- 🧷 コーディングルール（コメント言語等）: ✅ 適合
- 🧪 テスト: ✅ 適合
- 🔒 安藤（コードレビュー）: ✅ 実施 PASS
- 🎨 植草（UX）: ⏭️ スキップ — UI 変更が無いため
- 🧪 麗美（e2e）: ✅ 実施 PASS
- 🐰 CodeRabbit: ✅ 完了・未対応の指摘なし

総評: 上記2点（タイトル・changelog）の対応後にマージ可能な状態です。

11. ユーザーへの報告

サマリー内容をユーザーにも報告する。マージ判断はユーザーに委ねる（このスキルは勝手にマージしない）。

失敗時の対応

• PR が取得できない / リポジトリが特定できない: PR URL・番号と対象リポジトリをユーザーに確認する。推測で別の PR を点検しない
• サブエージェント（安藤・植草・麗美）の起動・レビューが失敗する: 失敗内容をユーザーに報告し、当該レビューを「未実施（理由: 失敗）」としてサマリーに明記する。無限リトライや、ルールを無視した代替手段で勝手に通過扱いにしない
• e2e でローカル環境（wp-env）が必要だが DB 操作が発生する: wp db import / wp db reset / wp db export などの DB 操作は 必ず実行前にユーザーに確認する。麗美にもこの点を伝達する
• CodeRabbit が長時間完了しない: タイムアウト時は rules/coderabbit-monitoring.md の「タイムアウト時の手動確認」を実施し、それでも判断できなければユーザーに状況を報告する。「指摘なし」と断定しない
• 判断に迷う・ルールに該当しないケースに遭遇した場合は、勝手に解釈を広げず、ユーザーにエスカレーションする