pr-walkthrough

PR のウォークスルー

現在のブランチのプルリクエストを把握できるよう、ローカルで動作する静的な HTML／CSS／JavaScript のウォークスルーを作成してください。4 つの独立したインタラクティブな D3 ビューで構成します。レビュー担当者が、異なる 4 つの視点から影響を受けるコードとプルリクエストを理解できるようにしてください。

• システム概要ビュー：プルリクエストが触れているサブシステムを簡潔に紹介する、単独で読めるコード概要です。グラフのように見せないでください。レビュー担当者がレビューを始める前に構成を把握できるよう、必要十分なアーキテクチャ上の背景を示す、展開済みのコンポーネントカードを少数表示します。このビューでは、プルリクエスト、変更されたファイル、レビューコメント、差分へのリンク、スクリーンショット、仕様、実装上の差分について言及しないでください。
• データフローグラフ：変更されたシステム内で、状態、データ、イベント、リクエスト、ファイル、アセット、またはレンダリング結果がどのように流れるかを示します。
• コード依存関係グラフ：変更されたコンポーネントが互いにどのように依存しているか、主要な境界がどこにあるか、どのファイルがエントリーポイントでどれがリーフ依存関係なのかを示します。
• ユーザー操作グラフ：ユーザーが何を行い、どの画面を操作し、その操作が実装内でどのように流れるかを示します。 このスキルは、キャンバスを使ったプルリクエスト理解の実験です。スライドショー形式を再現しないでください。すべての視点を 1 つのグラフにまとめないでください。ユーザーが切り替えられる 4 つの独立したキャンバスビューを生成し、各ビューにガイド付きツアーを用意して、サイトが最初から最後までプルリクエストについて解説するようにしてください。ウォークスルーの規模はプルリクエストに合わせてください。小規模なプルリクエストでは、包括的なアーキテクチャ文書ではなく、コンパクトなレビュー補助としてまとめてください。 このスキルはコードレビュー用ではありません。新たなレビュー指摘、承認／変更要求の推奨、網羅的な批評を生成しないでください。プルリクエストの HEAD コミット時点のコードベース全体、プルリクエストの差分、説明、プルリクエストで変更された仕様、そして人間またはエージェントによる既存のレビューコメントを使用して、レビュー担当者が変更をすばやく理解できるようにする案内マップを作成してください。

出力

自己完結型のサイトを次の場所に作成してください。

• .warp/pr-walkthrough/index.html このサイトは file:// URL から直接読み込める必要があります。開発サーバー、パッケージのインストール、バンドラー、ビルド手順を必要としないでください。 インライン CSS、インライン JavaScript、インラインデータを含む、単一の自己完結型 HTML ファイルを優先してください。ファイルを分割する必要がある場合は、相対パスのローカルファイルのみを使用し、ブラウザーの制限でローカルファイルの読み込みがブロックされる場合があるため、fetch() は使用しないでください。 D3 は、信頼できる CDN から、公式の固定バージョンを読み込んでください。変更する具体的な理由がない限り、ヘルパースクリプトのデフォルトを使用してください。
• https://cdn.jsdelivr.net/npm/[email protected]/dist/d3.min.js latest のようなバージョン未固定の URL、非公式ビルド、動的なパッケージ範囲は使用しないでください。UI 上で D3 の実装に関する注意書きを繰り返し表示しないでください。CDN／実行時の詳細は、必要な場合に限り検証ログまたは最後の注意事項に記載してください。 再利用可能で決定的な D3 レンダリングには、ヘルパースクリプト scripts/d3_canvas_runtime.py の使用を優先してください。このスクリプトは、Brandalf に準拠した CSS、D3 スクリプトを挿入する前にレンダラーを定義するインライン実行時ローダー、ズーム、パン、グラフ切り替え、検索、ノード詳細、ビューに合わせる機能、ガイド付きツアー操作を備えたグラフレンダラーを生成します。生成するウォークスルーごとに独自の D3 設定コードを書くのではなく、このヘルパーを使用してください。 生成されたキャンバスは、検証が必要な生成コードとして扱ってください。ウォークスルーを準備完了として報告する前に、生成した HTML に対して scripts/validate_d3_canvas.py を実行してください。キャンバスの初期化に失敗した場合、D3 の読み込みに失敗した場合、必要なグラフが不足している場合、ツアー操作が動作しない場合、ノード／エッジが描画されない場合、または利用可能なはずの環境でブラウザー検証ができない場合は、準備完了と報告する前にデバッグして再生成してください。ブラウザーを利用できる環境が実際にない場合は、準備完了ではなく、キャンバスの描画は未検証であると報告してください。

ブランドスタイル

ウォークスルーのビジュアルデザインを生成または改訂する際は、brandalf スキルを使用してください。Brandalf は、ホストされている Warp ブランドの正式な情報源を参照します。ウォークスルーの HTML/CSS を作成する前に情報源を取得し、適用してください。ホストされているブランド情報源を利用できない場合は、以下のフォールバックトークンを使用して作業を進め、最終回答でその旨を報告してください。 取得したブランド情報源に別の指定がない限り、Brandalf から導かれる以下のデフォルトを適用してください。

• Warp のダークなサーフェスを使用します。ページの背景には #121212、パネルには #1e1e1d／#292929、テキストには #faf9f6 または #ffffff を使用します。
• Warp のピンクのアクセントカラー #a43787 は、アクティブ状態、重要なリンク、フォーカスリング、選択中のツアーステップ、強調度の高いラベルに意図的に使用します。グラフの色には、セカンダリカラーとして緑 #34895c、青 #2e5d9e、紫 #754dac を使用します。
• UI／本文テキストには Matter を使用し、フォールバックには DM Sans, system-ui, sans-serif を指定します。コード、メタデータ、キャンバスのラベル、座標、ファイルパス、機械処理向けのスニペットには Matter Mono を使用し、フォールバックには Roboto Mono, ui-monospace, monospace を指定します。
• 文面は、事実を重視し、技術的かつ簡潔で、検証可能なものにしてください。誇張した宣伝文句や汎用的な流行語は避けてください。
• さりげない枠線のある、シャープでドキュメントらしいコンテナを優先してください。角丸は、カード、ノードの吹き出し、ツールチップ、ボタンの読みやすさが向上する場合にのみ使用してください。 推奨グラフカラー：
• システム概要ビュー：黄 #c0872a
• データフローグラフ：緑 #34895c
• コード依存関係グラフ：青 #2e5d9e
• ユーザーアクショングラフ：紫 #754dac
• アクティブ／フォーカス／選択中のノード：ピンク #a43787

ワークフロー

1. PR のコンテキストを把握する

リポジトリのルート、現在のブランチ、比較対象のベースを特定します。 現在のブランチに GitHub PR がある場合は、PR のベースブランチを使い、GitHub の差分リンク用に PR の URL を記録します。

gh pr view --json baseRefName,headRefName,title,body,url,state,reviewRequests,reviews,files

PR がない場合は、ローカルリポジトリの慣例またはリモートのデフォルトブランチからベースブランチを推定します。

git symbolic-ref --short refs/remotes/origin/HEAD

次に、レビューに必要な情報を収集します。

git --no-pager diff --stat <base>...HEAD
git --no-pager diff --name-status <base>...HEAD
git --no-pager log --oneline <base>..HEAD
git --no-pager diff <base>...HEAD

ビューを作成する前に、変更行数、変更ファイル数、概念的な広がりから PR の規模を見積もります。まずは、役に立つ範囲で最も小さなウォークスルーを作成します。

• ごく小さな PR：変更ファイルが約 1 件、または変更行数が 75 行未満です。各ビューにノード／カードを 2～3 個、ツアーのステップを 1～2 個配置し、挙動の理解に大きく役立つ場合を除いて、スクリーンショットやレビューの議論に関するノードは省略します。
• 小規模な PR：変更行数が約 250 行未満、または変更ファイルが 1～3 件です。各ビューにノード／カードを 3～4 個、ツアーのステップを 2～4 個配置し、各ノードの概要は 1 文にまとめ、詳細は短いものを最大 1 つにします。
• 中規模な PR：変更行数が約 250～800 行、または関連するファイルが複数あります。それぞれのノードが異なる概念を説明する場合に限り、各ビューに 4～7 個のノードを配置します。
• 大規模な PR：PR が複数のサブシステムにまたがる、新しいアーキテクチャを導入する、またはレビュー／仕様のコンテキストがかなり多い場合に限り、前述の充実した 5～12 個のノード範囲を使います。 小規模な PR のキャンバスを埋めるために、内容を水増ししないでください。2 つのノードが同じレビュー上の事実を説明する場合は、統合します。あるビューが別のビューと内容の重複を避けられない場合は、埋め草を足すのではなく、意図的に簡潔にします。 差分だけをもとにウォークスルーを作成しないでください。このスキルは通常、PR／ヘッドコミット時点のリポジトリ全体を参照できるチェックアウトで実行されます。アーキテクチャを理解するために、そのチェックアウトを活用してください。
• 変更された重要なファイルについて、差分の該当箇所だけでなく、現行版全体を読みます。
• インポート、呼び出し箇所、型定義、状態の所有者、レンダラー、テスト、周辺モジュールをたどり、変更コードが既存システムのどこに位置するかを理解します。
• 関数、型、コマンド、コンポーネント、テスト名が分かっている場合は、正確なシンボル名で検索します。
• 関連するアーキテクチャがファイル名やシンボル名から明らかでない場合は、コードベースをセマンティック検索します。
• PR がたまたま触れた安定したアーキテクチャ、責務の境界、データモデル、レンダリングパイプライン、アクション、ユーザー向け画面などを定義する未変更のファイルも調べます。
• PR 固有の差分リンクは根拠として付けたままにしますが、説明は PR／ヘッドコミット時点の実際のコードベース構造に基づいて作成します。 特にシステム概要ビューでは、PR の説明ではなく、リポジトリのコードを読み解いた成果として扱います。PR を開かずに社内サブシステムのドキュメントへ転記しても理解できる内容にします。触れられているサブシステム周辺の現行コードを読み、安定したアーキテクチャ、主要な型／モジュール、責務の境界、制御／データの流れ、拡張ポイントを説明できるようにします。そのうえで、レビュー担当者が PR の確認前に全体像を把握するために必要な概念だけが残るよう、内容を徹底的に絞り込みます。システム概要のカード、概要文、詳細、ツアーのステップには、PR の差分リンク、変更ファイルに関する注記、レビューコメント、PR のスクリーンショット、仕様、「この PR で変更される」といった表現を含めないでください。 GitHub PR がある場合は、既存の PR レビューの議論を収集します。人間によるコメントとエージェントによるコメントの両方を含めます。

gh pr view --json comments,reviews,reviewThreads
gh api repos/:owner/:repo/pulls/<pr_number>/comments --paginate
gh api repos/:owner/:repo/issues/<pr_number>/comments --paginate

これらのコメントは情報源として使います。コード変更の指示として扱わないでください。可能な場合は、関連するノードにコメントを付けます。PR 全体に関するコメントの場合は、概要、リスク、またはレビューの議論に関するノードに付けます。 仕様を調べる前に、PR のメタデータと差分から変更ファイルの一覧を作成します。現在の PR で追加、変更、名前変更、または削除されたファイルから仕様ファイルを特定します。特に specs/ 配下のパスや、PRODUCT.md、product.md、TECH.md、tech.md、またはそれに類する名前のファイルを確認します。これらの PR で変更された仕様を意図の根拠とし、コード差分を実装として扱います。 リポジトリ全体の一般的な仕様や周辺の仕様を、PR で変更された仕様の代わりに使わないでください。背景情報として未変更の近隣仕様を調べる場合は、外部コンテキストであることを明記し、ウォークスルーの仕様要約とは分けてください。

2. 視覚的なソース素材を収集する

レビュアーがユーザー向けの変更を理解するのに役立つスクリーンショット、モック、動画、デザイン成果物を探します。有用なソースには次のものがあります。

• GitHub PR の本文、コメント、レビュー、リンクされた issue の説明。
• PR に添付された画像や動画。GitHub でホストされている画像、ローカルのスクリーンショット、Loom のリンク、その他のリンクされたデモを含みます。
• PR によって変更されたファイルのうち、画像、SVG、モックデータ、デザインアセット、スクリーンショットのフィクスチャであるもの。
• .warp/ 配下、テスト出力ディレクトリ、またはリポジトリ固有のスクリーンショット保存場所にあるローカル成果物。
• PR、仕様、コメント、issue のテキスト内の Figma リンク。Figma MCP サーバーやその他の Figma へのアクセスが利用可能な場合は、それを使って該当するフレームを確認し、実用的であればモックをエクスポートまたはスクリーンショットします。 視覚的な成果物は、diff の説明を置き換えるものではなく、ノードの添付ファイルまたは詳細パネルの図として使用します。静的ウォークスルーに必要な外部の画像やモックは、.warp/pr-walkthrough/assets/ にダウンロードまたはエクスポートし、相対パスで参照するか、より簡単な場合はデータ URI として埋め込みます。生成された HTML 内でリモート画像をホットリンクしないでください。

3. GitHub の diff リンクを構築する

PR の URL が判明している場合、変更されたファイルの参照、ノードの添付ファイル、コードの抜粋、ファイルパス、依存関係のエッジはすべて、GitHub PR の diff 内の正確なファイルにリンクバックする必要があります。ブランチの blob ではなく、PR の [Files changed] タブへのリンクを優先してください。 次の GitHub PR diff URL 形式を使用します。

<pr_url>/files#diff-<file_anchor>

行単位のリンクには、diff 側の行アンカーを追加します。

<pr_url>/files#diff-<file_anchor>R<new_line>
<pr_url>/files#diff-<file_anchor>L<old_line>

ここで:

• <pr_url> は gh pr view --json url で取得した正規の PR URL です。
• <file_anchor> は、PR のファイル一覧または diff の b/<path> 側に表示される、変更されたファイルパスの小文字 16 進数の SHA-256 ダイジェストです。
• R<new_line> は diff の右側/新しい側の行にリンクします。
• L<old_line> は diff の左側/古い側の行にリンクします。 アンカーは手書きせず、決定的なヘルパーで生成してください。

4. PR を4つのガイド付きビューで分析する

HTML を作成する前に、4つのビューモデルを構築します。各ビューには、変更されたすべてのファイルではなく、注目すべきポイントを含めます。 各グラフについて、次の点を決めます。

• レビュアーが最初に理解すべきノードは何ですか？
• PR を最初から最後まで理解するのに最適なノードの順序は何ですか？
• グラフビューでは、どのエッジが各ノードをつなぎ、それぞれのエッジはどのような関係を説明しますか？
• 変更されたファイル、仕様、テスト、ビジュアル、既存のレビューコメントのうち、どれを各ノードに関連付けますか？
• レビュアーがそのノードをクリックしたとき、何を確認すべきですか？ コンテンツを確定する前に、重要な各ノードを PR/head コミット時点の実際のソースファイルと照合します。システム概要ビューでは、まず既存の担当モジュールと隣接する未変更モジュールを調べ、その後、差分を使って調査するサブシステムを特定します。他のグラフでは、差分を使って根拠を関連付け、PR 固有の経路を説明します。 各ビューにはツアーが必要です。ツアーには、ノード ID の順序と説明文を含めます。ツアーでは、意図的な順序でレビュアーを案内します。ファイルの順序に沿ってノードをただ選ぶだけにしてはいけません。 有向グラフでは、方向が視覚的に明確になるようにします。データフロー、コード依存関係、ユーザーアクションを表すエッジには、矢印の先端を付けて、ノードの下に隠れず、ターゲットノードの境界に明確に届くようにします。エッジラベルには、ソースからターゲットへの関係の方向を説明させます。システム概要ビューのエッジは、通常はゼロにします。エッジが必要に感じられる場合、そのビューはグラフの領域に戻っている可能性があるため、簡素化してください。 次のビューの役割を使います。
• システム概要ビュー：PR がたまたま触れているサブシステムのアーキテクチャを、独立したコード概要として説明します。PR の変更一覧、差分の要約、実装経路、依存関係グラフ、レビュアー用チェックリスト、包括的なサブシステムのドキュメントとして構成してはいけません。このビューには、PR の差分リンク、変更ファイルの注釈、レビューコメント、PR のスクリーンショット、仕様やイシューの意図を関連付けないでください。小規模な PR では、安定したコンポーネントの概念を2～3個使うことを優先します。大規模な PR では、すべてのカードが必要な場合に限り、最大4～7個まで使います。各カードはグラフのノードより視覚的に大きくし、キャンバス上にラベルだけでなく短い段落を表示します。この段落では、コンポーネントの定義と、全体像の把握に重要な理由を説明します。ただし、PR のレビューを始める前にレビュアーが状況を把握するために必要な範囲に厳密に限定してください。カードのタイトル、要約、詳細、ツアーの各ステップでは、システム全般の動作を説明し、PR に依存せず常に当てはまる内容にします。簡潔なカードでは、必要に応じて width: 340、height: 180、summaryLines: 5 など、カードの寸法を明示的に設定します。
• データフローグラフ：情報や状態の移動に重点を置きます。意図や仕様の入力から始め、ソース／デフォルト値／状態、レイアウト／レンダリングの出力、非同期アセットまたは検証ループへと続けます。
• コード依存関係グラフ：所有関係と依存方向に重点を置きます。仕様／エントリーポイントから始め、モデル／ビュー／コマンドの接点、エディターのレンダリング要素、テストへと続けます。
• ユーザーアクショングラフ：ユーザーの操作経路に重点を置きます。画面から始め、アクション、表示されるフィードバック、エラー／読み込み状態へと続けます。 概要ビュー以外で有用なグラフは、小規模な PR なら通常3～5ノード、大規模な PR なら5～12ノードが適切です。同じ概念上のポイントを、グラフごとに座標と説明文を変えて複数のグラフに表示してもかまいませんが、各ビューで同じ説明を繰り返すのは避けてください。

5. キャンバスのデータモデルを作成する

グラフデータは、window.PR_WALKTHROUGH_D3_DATA に代入する JSON として HTML 内に直接保存します。fetch() で JSON を読み込まないでください。 次の形式を使用します。

{
  "meta": {
    "title": "PR title",
    "prUrl": "https://github.com/owner/repo/pull/123",
    "baseRef": "master",
    "headRef": "feature-branch",
    "summary": "What the PR is trying to accomplish."
  },
  "graphs": [
    {
      "id": "system-overview",
      "label": "System overview",
      "color": "#c0872a",
      "summary": "Concise component overview for the affected subsystem.",
      "nodes": [],
      "edges": [],
      "tour": []
    },
    {
      "id": "data-flow",
      "label": "Data flow graph",
      "color": "#34895c",
      "summary": "How state and rendered output move through the change.",
      "nodes": [
        {
          "id": "intent",
          "title": "Intent",
          "kind": "overview",
          "x": 0,
          "y": 0,
          "summary": "The change this PR is trying to make understandable.",
          "details": ["Concise evidence-grounded explanation."],
          "files": [{ "path": "specs/example/product.md", "url": "<github_diff_url>" }],
          "comments": [{ "author": "reviewer", "body": "Existing review discussion.", "url": "<comment_url>" }],
          "links": [{ "label": "PR", "url": "<pr_url>" }]
        }
      ],
      "edges": [
        { "source": "intent", "target": "surface", "label": "default flows into" }
      ],
      "tour": [
        { "nodeId": "intent", "title": "Start with intent", "body": "Teach why this point matters." }
      ]
    }
  ]
}

座標とスケールに関するガイダンス：

• 開始ノードは左側または上側に配置します。
• 可能であれば、ツアーの経路は左から右、または上から下に配置します。
• ツアーのステップとエッジが視覚的にわかるよう、関連するノードを十分近くに配置します。
• 下位レベルの依存関係は、呼び出し元より右側または下側に配置します。
• システム概要ビューでは、スケールをグラフノードから展開されたリファレンスカードに変更します。カードの数を減らし、カードのサイズを大きくし、段落程度の長さの概要を記載して、シンプルで読みやすいレイアウトにします。PR の意図ではなく、中央のサブシステムの概念を中心に、同階層のアーキテクチャコンポーネントをコンパクトなリファレンスマップとして配置します。このビューには、PR の証拠、変更ファイルへのリンク、レビューコメント、スクリーンショット、仕様、PR 固有のノードを含めないでください。edges: [] を推奨します。
• 小規模な PR では、パンせずに各ビューを読みやすいよう、グラフの座標をコンパクトに保ちます。広範なマップより、短い左から右への連鎖を推奨します。

6. 静的サイトを構築する

サイトは、人とブラウザー自動化エージェントの両方が利用できる必要があります。 必須の UI 動作：

• D3 zoom を使用し、現在アクティブなグラフを描画する、ズームとパンが可能な SVG キャンバスを 1 つ用意します。
• 表示するビュー切り替え：システム概要、データフローグラフ、コード依存関係グラフ、ユーザーアクショングラフ。
• 表示するツアー操作：前のツアーステップ、次のツアーステップ、ツアーを再開、および ステップ 2 / 7 のようなインジケーター。
• アクティブなグラフ内のノードタイトル、ファイルパス、添付コメントテキストを検索できる入力欄。
• クリック可能なノードを用意し、クリックすると永続的な詳細パネルを開くか更新し、そのノードがツアーに含まれている場合はツアーをそのノードに同期します。
• 関係の意味を示すエッジラベル。
• キーボード操作：
  • 右矢印または n：次のツアーステップ。
  • 左矢印または p：前のツアーステップ。
  • 1：システム概要ビュー。
  • 2：データフローグラフ。
  • 3：コード依存関係グラフ。
  • 4：ユーザーアクショングラフ。
  • + または =：ズームイン。
  • -：ズームアウト。
  • 0：ズームをリセット。
  • f：ビューに合わせる。
  • /：検索にフォーカス。
  • Escape：検索または選択をクリア。
• コンピューター操作エージェントがクリック操作とスクリーンショットの取得を確実に行えるよう、安定した見出し、ボタンラベル、data-graph-id、data-node-id、data-edge-id、data-tour-index 属性を用意します。 必須のコンテンツ動作：
• PR タイトル、base/head の参照先、簡潔な意図の概要をキャンバスの上または横に表示します。
• データには、system-overview、data-flow、code-dependency、user-action のビュー定義をちょうど 4 つ含めます。
• 各ビューにそれぞれ独自のノードとツアーを用意します。データフロー、コード依存関係、ユーザーアクションのグラフには、有向エッジを含める必要があります。システム概要ビューは通常エッジをゼロにし、グラフではなく概要として読めるよう、表示される段落テキストを含む大きめのカードを使用します。
• 有向グラフで描画されるすべてのエッジは、ターゲットノードに向いた表示可能な矢印を備え、ソースからターゲットへの関係を示すラベルを付ける必要があります。
• システム概要の内容は PR に依存せず、対象を絞ります。PR のレビュー時に必要な範囲に限り、アプリのアーキテクチャをレビュアーに説明し、PR、変更されたファイル、レビューコメント、スクリーンショット、仕様、実装上の差分には触れないでください。PR 固有の根拠や注釈は、代わりにデータフロー、コード依存関係、またはユーザーアクションのグラフに配置します。
• 各ツアーステップはノードを指し、ウォークスルーのその時点でそのノードが重要な理由を説明する必要があります。
• 各ノードには詳細パネルで説明文を表示します。システム概要のカードには、キャンバス上にも段落全体を表示し、PR の変更ではなく、変わらないコードの概念を説明します。
• 変更されたファイルへの参照は、それぞれ GitHub の PR diff URL にリンクします。
• PR で変更された仕様は、ノードまたはノードへの添付ファイルとして表現します。PR で仕様が変更されていない場合は、明示的に「PR で変更された仕様は見つかりませんでした」というノードまたは注記を含めます。
• 既存の人間およびエージェントによるレビューコメントは、関連するノードに添付するか、レビュー討議ノードに要約します。
• 視覚的な成果物は、詳細パネルのノード添付ファイルとして表示します。
• ごく小規模または小規模な PR では、仕様の欠如、レビュー討議、ビジュアルについて、既存のノードの詳細パネルに簡潔な注記として記載します。ただし、レビュアーが PR をどう読むべきかに実質的な影響を与える場合は、独立したノードとして扱います。
• Brandalf に沿った Warp スタイルを使用します。暗い #121212 の背景、オフホワイトのテキスト、Matter／Matter Mono のタイポグラフィ、ピンクのアクティブアクセント、ブランドパレットのグラフカラーを使用します。 ヘルパーの出力を使用：

python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --css
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --runtime
python3 .agents/skills/pr-walkthrough/scripts/d3_canvas_runtime.py --template --data graph.json > .warp/pr-walkthrough/index.html

7. ウォークスルーを検証する

完了する前に、次のことを行ってください。

1. 生成された index.html のパスを開くか、正確な file:// URL を出力します。
2. 明示的に記載された、固定バージョンの公式 D3 CDN ランタイムを除き、HTML がネットワークアクセスを必要としないことを確認します。
3. D3 が具体的な固定 URL を使用し、latest パッケージへの参照がないことを確認します。
4. ローカルの JSON／データ読み込みに fetch() が使用されていないことを確認します。
5. グラフデータに必要なグラフ ID（system-overview、data-flow、code-dependency、user-action）だけが含まれていることを確認します。
6. 必要なコントロールがすべて含まれていることを確認します：Fit to view、Reset zoom、System overview、Data flow graph、Code dependency graph、User action graph、Previous tour step、Next tour step、Restart tour。
7. ブラウザーで各ビューにノード／カードが表示されること、システム概要には PR 固有の添付ファイルがない展開済みの段落カードが表示されること、概要以外のすべてのグラフに矢印が見える有向エッジが表示されることを確認します。
8. グラフの切り替え、ツアーのナビゲーション、キーボードショートカット、ズーム、パン、ビューに合わせる操作、検索、ノード詳細の選択が機能することを確認します。
9. すべてのグラフに空でないツアーがあり、各ツアーステップが既存のノードを指していることを確認します。
10. システム概要カードを除き、すべてのノードに説明文と、該当する場合は関連する変更ファイルへのリンクがあることを確認します。システム概要カードには PR の差分リンク、変更ファイルの注釈、レビューコメント、スクリーンショット、仕様、実装の差分を含めないでください。
11. PR で変更された仕様と既存の PR レビューコメントを取得し、グラフに反映するか、存在しない／利用できないことを明示的に報告したことを確認します。
12. ウォークスルーで参照されているスクリーンショット、モック、Figma エクスポート、変更画像、動画サムネイルが、リモートの直リンクではなく、ローカルの相対アセットまたはデータ URI であることを確認します。
13. サイトに Brandalf／Warp のスタイルが適用されていることを確認します。
14. 再利用可能なバリデーターを実行します。

python3 .agents/skills/pr-walkthrough/scripts/validate_d3_canvas.py --html .warp/pr-walkthrough/index.html --require-browser

検証に失敗した場合、またはブラウザーを使用できる環境で検証を実施できない場合は、ウォークスルーの準備が完了したと報告しないでください。グラフを修正するか、レンダリングが未検証であると報告してください。

8. Cloudflare Pages での任意の一般公開

デフォルトでは、ウォークスルーの成果物は .warp/pr-walkthrough/ の下に保管し、バージョン管理の対象外にします。ユーザーが一般公開 URL または再利用可能な CLI 公開ワークフローを求めた場合は、ウォークスルーの検証に合格した後、Cloudflare Pages Direct Upload を優先してください。 前提条件：

• ユーザーが Cloudflare アカウントを持っている必要があります。
• ローカルで対話的に使用する場合は、Wrangler のログインを一度実行します。

npx wrangler login

• まだ存在しない場合は、Pages プロジェクトを一度作成します。

npx wrangler pages project create warp-pr-walkthroughs --production-branch main

生成したウォークスルーディレクトリをアップロードルートとして使用します。

npx wrangler pages deploy .warp/pr-walkthrough \
  --project-name warp-pr-walkthroughs \
  --branch pr-<pr-number>-$(git rev-parse --short HEAD) \
  --commit-dirty=true

安定した「最新のウォークスルー」URL を使用するには、代わりに本番ブランチへデプロイします。

npx wrangler pages deploy .warp/pr-walkthrough \
  --project-name warp-pr-walkthroughs \
  --branch main \
  --commit-dirty=true

Wrangler は、デプロイ URL と、本番以外のブランチへのアップロードの場合はデプロイエイリアス URL も出力します。標準出力から URL を取得し、ユーザーに報告してください。本番ブランチの URL は通常、次のとおりです。

https://warp-pr-walkthroughs.pages.dev

ブランチプレビュー URL は通常、次の形式です。

https://pr-<pr-number>-<sha>.warp-pr-walkthroughs.pages.dev

公開に関する重要な注意事項：

• 新しく作成した Cloudflare Pages プロジェクトでは、プレビューサブドメインの TLS 設定が完了する前に本番 URL が利用可能になることがあります。Chrome でプレビュー URL を開いた際に ERR_SSL_VERSION_OR_CIPHER_MISMATCH エラーが発生した場合は、しばらく待ってから再試行するか、--branch main でデプロイし、すぐ共有するには本番 URL を使用してください。
• wrangler が作業ディレクトリに未コミットの変更があると警告した場合は、コミットする必要のない生成済み .warp/ 成果物に対して --commit-dirty=true を指定します。
• 非公開のコードや機微な PR コンテキストについては、ユーザーがその公開を明示的に了承しない限り、公開 URL に公開しないでください。保護されたホスティング、Cloudflare Access、またはローカルの file:// URL を使用してください。
• PR のコメントには短い公開 URL だけを投稿してください。ユーザーが明示的に求めない限り、生成された HTML 成果物をリポジトリにコミットしたり、埋め込んだりしないでください。

オリエンテーションの指針

取り上げる内容を決める際は、次の点に留意してください。

• PRの目的、設計、アーキテクチャ、ユーザーへの影響をレビュアーが理解するうえで必要な、最小限の要点を強調します。
• ノードは少数に絞り、質を重視します。100～200行のPRであれば、通常はすべてのビューを通じて、合計約10～16個のノード／カードでコンパクトなウォークスルーを作成します。30個以上にはしません。
• アーキテクチャの正確な情報源には、PR／ヘッドコミット時点のコードベース全体を使用します。差分から変更内容を確認できますが、変更された部分の意味を理解するには既存のコードが役立ちます。システム概要ビューは、差分ではなくコードベースの調査に基づいて作成します。
• システム概要では、読者がPRをレビューするのに十分な見通しを得た時点で止めます。間接的に関係するサブシステムや、実装上の依存関係をすべて含める必要はありません。
• 概念、サブシステム、状態の所有者、ユーザー向けの画面や機能、重要な仕様、レビューで議論になりそうな箇所には、ノードを優先して割り当てます。
• 原因と結果、データの移動、呼び出し／依存関係の方向、ユーザー操作の流れは、エッジで示すことを優先します。
• 説明する順序はツアーで示します。グラフで関係性を表現できますが、理解を導くのはツアーです。
• 生成ファイル、機械的な名前変更、フォーマットのみの変更、繰り返しのボイラープレートは、強調しないようにします。
• 上位レベルの各要素が、なぜそれぞれの下位レベルの依存関係を必要とするのかを説明します。
• 行動上またはアーキテクチャ上のリスクは、特に仕様、PRの説明、テスト、既存のレビューコメントに記載されている場合、オリエンテーションの注記として示します。
• テストを、それが検証するノードまたはエッジに関連付けます。
• 仕様とコードに食い違いがある場合は、それを隠さず、ノードまたは注釈として示します。
• 新たなコードレビューを実施しようとしないでください。レビュアーを案内する過程で気づいた点は、すでにPRのレビューで議論されている場合を除き、問題点として断定せず、確認すべき箇所として示します。

最終回答

次の内容を報告します。

• 生成されたウォークスルーのパス。
• file:// URL。
• 推定したベースブランチとPRのタイトルまたはブランチ名。
• 差分リンクに使用したGitHub PRのURL。
• PRのレビューコメントが見つかり、含められたかどうか。
• D3キャンバスの検証に合格したかどうか。
• 公開した場合は、Cloudflare Pagesの公開URLと、それが本番URLかブランチプレビューURLか。
• 重要な注意点、不足している仕様、または実施できなかった検証。