pr-tour

PR ツアー

差分を上から下まで読むレビュアーは、説明に適した順序ではなく、Git が出力するアルファベット順で読みます。コードに AI が書いたとラベルを付けても、人々がより注意深く読むようにはなりません。最初に読む内容を変えることが重要です。このスキルでは、まず「なぜ」を示し、次に重要なファイル、最後にノイズを示します。

このツアーは注意を促しますが、評価はしません。マージの可否もセキュリティの可否も判断せず、「折りたたみ済み」は読む価値が低いという意味であり、「確認済み」という意味ではありません。人間（HTML）にもエージェント（JSON）にも同じ内容を提供するため、敵対的なレビュアーは重大度の高い項目から確認できます。

スクリプトはこのファイルと同じ場所にある scripts/ にあります（Node ≥ 18、依存関係なし、gh にログイン済み）。これを HTTP 経由で取得した場合は、scripts/*.mjs と references/config.md を curl -sSL でプレーンテキストとして取得してください。

一連の流れ

0. 新しいセッションで開始します。 ツアーは新しいセッションで実行し、差分を書いたセッションでは決して実行しないでください。作成者は自分の盲点を指摘できません。
1. 計算します。 node scripts/tour.mjs <pr-number> を実行します（リポジトリの外では --repo owner/name を追加します。PR 作成前は --git main...feat/x を指定します。仕様やレビュー契約が別の場所にある場合は --spec <path> を指定します。出力フォルダーを変更するには --out <dir> を指定します）。.pr-review/tour-<n>.json に FACT 項目、ファイルごとの分類、読み進める順序、見つかったすべてのソースからの作成者の言葉を、重要度の高い順に書き込みます。ソースは、仕様（名前にブランチ名を含む、docs/、specs/、.scratch/、contracts/ 内の Markdown ファイル）、PR の説明、リンクされた Issue とコミット内の #123 参照、コミットメッセージ、タイトルです。意図のステータスは spec、described、title only、UNKNOWN のいずれかです。最後にノイズをまとめます。ロックファイル、名前変更、書式設定、生成ファイル（ORM スナップショット、ミニファイ済みバンドル、大きな機械生成 JSON、生成を示すヘッダーがあるファイル。全リストは references/config.md を参照してください）が対象です。ノイズファイルが ASK WHY ファイルになることはありません。ノイズの行数を出力します。差分が空の場合はエラーでここで停止します。
2. 差分を読みます。 読み進める順序で差分を確認します（gh pr diff <n> または git diff）。ノイズも含めてください。人が読む際にはまとめられていますが、あなたが読むときは省略しないでください。チェックアウトせずに、PR のヘッド時点の周辺ソースを読みます（他の人が同じチェックアウトを共有している可能性があります）。git fetch origin <head> を実行し、続けて git show "origin/<head>:<path>" を実行します（引用符が必要です。zsh は :a と :s を修飾子として解釈します）。同じコードに触れている他のオープン PR も対象にしてかまいません。別のオープン PR を壊す変更は、中程度の項目です。
3. WHY を .pr-review/tour-<n>.notes.json に書きます。 完全な形式、記入例、重要度の基準については references/notes.md を参照してください。概要は次のとおりです。
   • attention — ここでは任意ですが、pr-triage が実行する場合は必須です。PR に必要な注意の度合い（critical / high / medium / low）、何が起きたか、その理由、判断の根拠となる行を記載します。ツアーの上部にバッジとして表示されます。
   • whatItDoes — 差分が実際に何をするのかを 1〜2 文で記述します。作成者の意図ではなく、モデルによる読み取りとして表示されます。
   • why、points、shape、diagrams、chapters — 作成者の理由（引用）、キーワードリンク付きの 3〜5 行の概要、1〜3 個の構造ビュー、フローまたは構造に変化がある場合は 0〜2 個の Mermaid 図、章ごとにまとめたウォークスルーです。すべて任意です。リファレンスを参照してください。
   • explains — 意図のマップです。作成者が PR で行うと述べたことをそれぞれ逐語的に引用し、それを実装するコードファイルを記載します。何も説明していないファイルは含めないでください。ゲートによって ASK WHY として列挙されます。これはツアーが示す中で最も役に立つものです。
   • claims — 作成者が行う、確認可能な約束（「ゲストのチェックアウトには変更なし」など）を逐語的に引用し、それぞれ確認すべき行を示します。
   • items — LOOK HERE のポインターは最大 8 件です。それぞれに severity、file、line、該当行の code の逐語的な断片、title、why を指定します。結論ではなく、確認事項として記述してください。CI がすでに検出するものは省きます。
   • fileNotes — ノイズではないファイルごとに、太字の要点と 2〜5 個の箇条書きを記載します。
4. ゲートを実行します。 node scripts/annotate.mjs <tour.json> <notes.json> を実行します。作成者のテキストに逐語的に一致しない引用、code が含まれない行へのポインター、意図のマップ内のノイズファイル、8 件を超える項目、判定を示す言葉がある場合は拒否します。次に、説明されていないファイルと一致しない引用を導き出し、読み進める順序を再計算します。修正するのはノートであり、チェックではありません。再実行しても安全です。
5. レンダリングします。 node scripts/render.mjs <tour.json> を実行すると、同じ場所に .html が書き込まれます。ビューアーとデータを内包する単一ファイルで、サーバーは不要です。CI アーティファクトとして安全に公開できます。報告する前に内容を確認してください。ブラウザーがあればブラウザーで確認し（file:// がブロックされる場合は python3 -m http.server -d .pr-review でフォルダーを配信します）、それができない場合も、少なくとも JSON 内の WHY パネルのテキストが適切か確認してください。
6. チャットで報告します。 HTML のパス、意図のステータス、説明されていないファイル、file:line 形式の重要度が高い項目、ノイズの行数を報告します。

厳守事項

• 指摘し、評価はしないでください。 「LGTM」「問題なさそう」「承認」「悪用可能」「問題なし」「レビューするものはない」などの表現は使わないでください。ゲートはよくある言い回しを拒否します。言い換えて回避しようとしないでください。
• 意図を決して作り上げないでください。 意図として扱うのは作者の言葉だけです。要約は、あなたの見解であると明示された whatItDoes に記載してください。ASK WHY リストを問題なく見せるために、引用を拡大解釈してファイルに当てはめないでください。説明のないファイルは指摘事項であり、失敗ではありません。
• 事実はスクリプトから得てください。 FACT 項目を自分の見解として言い直したり、退けたりしないでください。文脈上問題のない FACT がある場合は、項目またはファイルの注記でその理由を述べ、判断はレビュアーに委ねてください。
• 読み取り専用です。 PR についてコメント、承認、変更をしたり、コードを編集したりしないでください。出力するファイルは .pr-review/ 内の 2 つだけです。

ツアーでは確認できないこと

• コードが動作するかどうか。 ツアーでは実行しません。実行してください。
• 脆弱性。 不足しているセキュリティ上の判断を確認します。スキャナーではありません。CI で実際のスキャナー（Trivy、opengrep）を実行してください。
• 問題のないノイズではないもの。 ロックファイルに悪意のあるパッケージが含まれることがあります。「フォーマットのみ」のファイルはヒューリスティックで検出されます。折りたたまれたファイルもワンクリックで確認でき、その理由とともに一覧表示されます。
• 差分の外にあるテスト。 「名前が一致する変更済みテストがない」からといって、そのファイルを対象とするテストがないとは限りません。

JSON を読むエージェント向け

intent.status と unexplained[] で全体像、すなわち作者が述べたことと、その説明では説明できない変更済みファイルを確認できます。explains[] は引用とファイルを対応付け、unmatched[] は対応する変更のない引用を一覧表示します。items[] にはすべての指摘が含まれます。source（fact = スクリプト、model = 行を確認済み、map = 説明のないファイル）、severity、file、line、side、text、why が記録されています。order[] は各位置に why を添えた閲覧順で、files[] には差分の塊が含まれます。severity: "high" から確認してください。intent.status: "UNKNOWN" は、照合対象となる仕様がないことを意味します。推測せず、その旨を伝えてください。スキーマ： references/config.md。

完了の条件

• tour-<n>.json が annotate.mjs を通過し、tour-<n>.html が存在すること。
• LOOK HERE の各項目が差分内の実在する行を指し、すべての主張が原文からの逐語引用であること。
• チャットのレポートに、意図のステータス、説明のないファイル、高重要度の項目が記載されていること。

意図の検索順序と新しいセッションを使うルールは、Matt Pocock の code-review スキル（MIT）を参考にしています。

最終確認日：2026-09-25、Claude Code 使用（dmoka/skills #1 に同梱）