pr-evidence-capture

name	pr-evidence-capture
description	UI 変更や状態遷移を伴う PR に、E2E テスト計画・操作後スクリーンショット・検証結果・検証データの副作用を確認エビデンスとして残す。 gh image で画像をアップロードし、Chrome DevTools MCP で画面を操作・撮影し、gh でテスト計画と結果を PR コメントへ投稿する際に使用。 「PR にスクショを貼る」「UI エビデンスを残す」「E2E 確認結果を PR にまとめる」「レビュー用に画面の証跡を添付」と依頼された時に適用。 内部ロジックのみの変更や、既存の自動テストで担保できる変更には使わない。コミット作成や PR 本体の作成フローには使わない。

PR 確認エビデンスのキャプチャ

UI 変更・状態遷移・検証データへの副作用を含む PR に対し、レビュアーがローカルを立ち上げずに確認範囲を追える形でエビデンスを残す。コード差分と確認結果を同じ場所（PR コメント）へ集約する。

ツールの役割分担

役割	使うもの
PR 情報の取得・本文編集・コメント投稿	gh
ブラウザ操作・スクリーンショット取得	Chrome DevTools MCP
スクリーンショットのアップロード	gh image 拡張

役割を混ぜない。画像アップロードは gh image、PR 投稿は gh pr comment に分けると安定する。gh 単体ではローカル画像を PR コメント用の user-attachments asset へ上げる導線がないため、アップロードは必ず gh image を使う。

ワークフロー

1. gh で対象 PR と差分を取得し、E2E テスト計画を作る（分岐・状態遷移を切り出す）
2. Chrome DevTools MCP で対象画面を必要な状態まで操作し、スクショ取得
3. 戻る/キャンセル/閉じる/リセット系は scripts/verify-shot-diff.py でハッシュ比較
   → 同一なら再操作して取り直す（exit 1）
4. gh image <path> でアップロードし、出力された Markdown 参照を得る
5. gh pr comment --body-file - （HEREDOC）でテスト計画・スクショ・結果・検証データ副作用を投稿

各ステップの具体コマンドと PR コメントテンプレートは references/commands.md を読む。

Step 1: E2E テスト計画を作る

gh pr view / gh pr diff で差分を取得し、計画を作る。UI フロー変更では「表示されたか」だけでなく、分岐ごとの状態遷移をケースに分ける。

• 対象項目がある場合に確認モーダル等が表示される
• 確認すると後続処理（状態遷移）へ進む
• キャンセルすると開始前の状態のままになる
• 対象が 0 件の場合は分岐を挟まず処理される

差分から拾える観点とプロダクト上の重要観点は一致しないことがある。計画は任せきりにせず、重要フローを補う。

Step 2-3: スクショ取得とハッシュ検証

Chrome DevTools MCP で対象ページを開き、必要な画面状態（モーダル展開・エラー表示・空状態・モバイル幅など）まで操作してから撮影する。

操作後に見た目が操作前へ戻るケース（キャンセル後・戻る・閉じる・リセット）は、別ファイルでも同一ハッシュになりエビデンスとして弱くなる。python3 scripts/verify-shot-diff.py <操作前> <操作後> で sha256 を比較し、一致したら操作を再実行して取り直す。PR コメント内の説明にも「どの操作後か」を明記する。

Step 4-5: アップロードと投稿

gh image <image-path>... でアップロードし、出力された Markdown 画像参照をコメントへ埋め込む。PR コメント本文は HEREDOC または --body-file - で渡し、画像リンクや表が崩れないようにする。

投稿には次を含める。

• 何を確認すべきか（E2E テスト計画）
• 実際に何を確認したか（ケースごとの結果表）
• 画面はどう表示されたか（ケース見出し付きスクショ）
• どのケースが成功/失敗したか
• 検証操作で開発環境の検証用データへ残った副作用（検証後ステータス、再検証時の注意）

使うべき PR / 使わない PR

使うべき	使わない
モーダル・フォーム・状態遷移を変更する PR	内部ロジックのみの変更
操作で検証用データの状態が変わる PR	既存の自動テストで十分担保できる変更
レビュアーがローカルを立てないと判断しにくい PR	テストログ・差分説明で足りる変更
キャンセル/戻る/対象 0 件など分岐見落としが起きやすい PR

すべての PR に同粒度のスクショを要求すると重くなる。上記に限定する。

制約

• GitHub コメントでは絵文字を使わない。
• シェルのクォーティング問題は HEREDOC で回避する（コードブロック・表・画像リンクを含む本文は特に）。
• 検証で進めた検証用データは次回の再検証に使い回さず、別データを用意する。

エラーハンドリング

• gh image のトークン切れ: gh image check-token で確認し、必要なら gh image extract-token または GH_SESSION_TOKEN を設定して再実行する。
• スクショが同一ハッシュ（verify-shot-diff.py が exit 1）: 操作を再実行して取り直す。撮るだけではエビデンスにならない。
• インライン投稿が崩れる: -b/-f の直接渡しをやめ、--body-file - の HEREDOC に切り替える。