visual-recap

ビジュアルリキャップ

/visual-recap は、差分に向けたものではなく、差分からビジュアルプランを作成します。これはフォワードプランニングの逆です。これから行う変更を説明する代わりに、行単位のレビューよりも高い視点から、たった今行った変更を説明します。同じプランのデータモデルがどちらの方向にも使われます。スキーマ、API、ファイル、アーキテクチャの変更は、フォワードプランで使われるものと同じ data-model、api-endpoint、file-tree、diagram ブロックになりますが、今度はすでに存在する作業を要約します。レビュアーは、具体的な行を確認するために時間を割く前に、変更の全体像を把握できます。

エージェントネイティブプランとして公開する — インライン表示は禁止

成果物は、Plan MCP コネクターの create-visual-recap で作成する、公開済みの Agent-Native Plan でなければなりません。インラインのチャットコンテンツ（Markdown の文章、ASCII のスケッチ、表、フェンスで囲んだ「ワイヤーフレーム」、「リキャップはこちら」といった要約を含む）は絶対に使用しないでください。リキャップの価値は、ホストされたインタラクティブで注釈可能なプラン全体にあります。インラインの要約は、質を落としたリキャップではなく、リキャップが置き換えるものです。plan（または旧式の agent-native-plans）ツールが表示されない場合は、まずホストの tool_search を使ってツールを探してください。それでも見つからない場合は、作り置きのインラインリキャップを出さずに処理を中止し、クライアントに応じた再接続手順をユーザーに案内してください。公開前、またはコネクターや認証のエラーが発生した場合は、このスキルディレクトリにある references/connection.md を読んでください。ここには、インライン表示禁止ルール、コネクターの検出方法、クライアントごとの再接続手順が記載されています。唯一の例外は、以下で説明するローカルファイルのプライバシーモードです。

ローカルファイルのプライバシーモード — references/local-files.md を読む

ユーザーがホストされた Plan データベースへの書き込みを一切望まない場合（DB 書き込みなし、Plan MCP での公開なし、完全なローカル／オフライン／プライベートのリキャップ、または AGENT_NATIVE_PLANS_MODE=local-files）、スキーマのみを参照する get-plan-blocks カタログ検索以外のホストされた Plan ツールは呼び出さないでください。ローカルの recap collect-diff／scan／build-prompt --local-files ヘルパーを使って差分を読み取り、ローカルの MDX フォルダーを作成し（kind: "recap" および localOnly: true を設定）、plan local check、plan local serve --kind recap、plan local verify --kind recap でプレビューしてください。ローカルファイルモードを使う前に、このスキルディレクトリにある references/local-files.md を読んでください。完全な仕様はここに記載されています。

使用するタイミング

PR やコミットの規模が大きい、複数のファイルにまたがる、またはスキーマ、API コントラクト、アーキテクチャに関わり、レビュアーが生の差分を読む前に構造化ブロックで変更を把握できると役立つ場合に、リキャップを作成します。GitHub Action を使えば、PR の差分から自動生成できます。エージェントは「この PR をリキャップして」「このブランチで何が変わったか見せて」といった依頼に応じて生成できます。小規模な変更、単一ファイルの変更、明らかな差分の場合は省略してください。リキャップはレビューの手間を増やすため、小さな変更ならプレーンな差分で確認するほうが速く済みます。

作業単位全体をリキャップする

すでに作業が行われた後のチャットスレッドで /visual-recap が呼び出された場合、デフォルトの対象範囲は直近のユーザーメッセージ、ツールの操作、フォローアップ修正だけではなく、現在の作業単位／スレッド全体です。会話全体を確認し、そのスレッドに属する変更をまとめてください。最初の実装作業、その後のバグ修正、UI のフォローアップ、テスト、変更セット、スキル／指示の更新、生成されたプラン／ソース成果物、リキャップを開けるようにするために必要なローカルのインポート／リンク修正が対象です。

現在の差分と会話のコンテキストを使って、スレッドに属する変更と、スレッド開始前から存在していた無関係な未コミット作業を区別してください。事前に存在していた無関係な編集は除外します。対象範囲が本当に曖昧で推測できない場合は、公開前に前提を明示するか、簡潔な質問をしてください。

フィードバックを受けて既存のリキャップを更新する場合は、新たな修正を含めたうえで、スレッド／作業単位全体を引き続き網羅するようにリキャップを改訂してください。ユーザーが対象範囲を狭めるよう明示的に依頼しない限り、広範なリキャップを直近のフィードバックだけを対象とする狭いリキャップに置き換えないでください。

要約本文は簡潔に保つ

生成する計画本文に、定型的な導入、免責事項、出典情報、要約の文章ブロックを追加しないでください。特に、要約は参考情報であること、レビュアーは引き続き差分を確認する必要があること、変更されたファイル数、または要約を生成した ref／作業ツリーを述べるだけの rich-text ブロックを作らないでください。計画のタイトル、概要、そしてファイルごとの変更統計を示す file-tree に、すでにその情報が含まれています。

構造化ブロックだけでは伝えられない変更の具体的な情報、つまり目的、実際の互換性リスク、差分から読み取れる重要な判断、または根拠に基づくレビュー上の注意を伝える場合に限り、文章ブロックを追加してください。

要約には十分な内容を含める

簡潔であることと、内容が乏しいことは同じではありません。要約がワイヤーフレームと一文だけでは、定型的な文章が多すぎるのと同じくらい、レビュアーの役に立ちません。視覚的・構造的な要点（ワイヤーフレーム、data-model、api-endpoint、diagram）に加えて、十分な内容を含む要約では実装上の根拠も示してください。

• 作成前に、画面、状態、変更箇所を簡潔に洗い出してください。差分から確認できる変更対象のルート、コンポーネント、ポップオーバー／ダイアログ、ロール／アクセス状態、空／エラー状態、共通の抽象化を列挙します。最終的な要約では、意味のある各項目をブロックで表すか、小規模、重複、またはユーザーから見えないことを理由に意図的に省略してください。
• 変更されたファイルを、各エントリーの change フラグとともに示す file-tree を含めてください。これにより、レビュアーは作業の範囲をひと目で把握できます。
• 主要な変更ファイルの差分を分割し、単一の横並び tabs ブロック内にまとめてください。## Key changes の rich-text 見出しの下に配置し、各ファイルを1つのタブにします（デフォルトの向き）。各タブには1行の summary と、いくつかの annotations を付けます。こうすることで、レビュアーは全体像から重要なコードへすぐに移れます。縦型のサイドレールではなく、横並びのファイルタブを使ってください。選択したファイルに並列差分を表示するための十分な幅を確保できます。

「使用する場面」で説明しているように、プレーンな差分のほうがレビューしやすい、本当に小規模な変更に限り、差分の付録を省略してください。要約する価値のある変更では、file-tree と主要な変更箇所の差分を計画に含めてください。

標準的な構成と分量の上限

優れた要約は、次の構成に沿って上から順に並びます。

1. UIへの影響を示す見出し — 描画されるUIが差分で変わる場合は、最初にワイヤーフレームを配置します。
2. 変更内容と理由を伝える短い説明（rich-text）：1〜3段落。
3. スキーマやコントラクトの変更を示す data-model／api-endpoint ブロック。
4. change フラグ付きで変更されたファイルを示す file-tree。
5. ## Key changes — diff／annotated-code をまとめた横並びの tabs ブロック1つ。

要約をレビューしやすく保つための分量の上限：

• 主要な変更タブは3〜8個にします。大規模な変更で3個未満では情報が足りず、8個を超えると要約として機能しなくなります。
• 各 diff／annotated-code の抜粋は要点に絞り、各タブで約150行未満を目安にします。長いファイルはすべてを貼り付けず、残りを要約するかリンクしてください。
• タイトルは最大約70文字、概要は1〜3文にします。

これらの上限は、要約にかけるコストの上限でもあります。網羅性を理由に超えてはならず、最初の逐次確認が終わったあとに差分全体を読み直してはいけません。その確認中に記録したメモをもとに作業してください。

GOOD. ファイル数25の認証機能変更：ログイン画面の変更前／変更後のワイヤーフレーム、2段落の説明、セッションテーブルの差分を反映した data-model、新しいリフレッシュルートの api-endpoint、変更フラグ付きの file-tree、そして ## Key changes の下に、重要なコード部分を示す1行の summary といくつかの注釈を付けた、要点を絞った5つのタブ。

BAD. 要約や注釈のない、分割されていない巨大な差分の貼り付け。または、40ファイルの変更を、ワイヤーフレーム1つ、1文、ファイル一覧だけの3ブロックで済ませ、結局レビュアーが生の差分に戻らざるを得ない簡素な要約。

UI の変更にはワイヤーフレームが必要です

差分によって、レンダリングされる UI、レイアウト、密度、視覚的な状態、操作 affordance、ナビゲーション、コントロール、メニュー、ダイアログ、またはデザイントークンが変更される場合、要約には 1 つ以上のワイヤーフレームを必ず含めてください。文章やファイルの差分は、視覚的な変更を示すものの代わりにはなりません。

ワイヤーフレームを選ぶ前に、差分から UI の網羅性を確認してください。

• 変更が現れる入口となる画面を特定します。ページヘッダー、リスト行、ツールバー、ルートシェル、メニューのトリガーなどが該当します。
• 開いたり変化したりする操作画面を特定します。ポップオーバー、ダイアログ、タブ、シート、ドロップダウン、インラインエディター、トーストなどが該当します。
• 遷移先、またはその後も維持される状態を特定します。公開ページ、読み取り専用ビュー、空の状態、エラー状態、読み込み状態、権限拒否状態、保存済み／共有済みの状態などが該当します。
• 権限が変わる場合は、アクセス権またはロールによる違いを特定します。オーナー／管理者／編集者と、閲覧者／管理者以外との違いは視覚的な動作であり、簡潔なマトリックス、対になるワイヤーフレーム、または明確なラベル付きの状態遷移で示す必要があります。

UI が中心の PR では、入口画面の変更前／変更後を 1 組示すだけでは不十分です。変更された入口、主な操作画面、遷移先／目的の状態を示してください。差分によってタブ、ロールに応じたコントロール、公開／非公開の表示、招待／管理のフロー、破壊的な操作、または空／エラーの分岐が加わる場合は、状態を追加してください。

レビュー内容が明確になる、最小限の視覚的な範囲を選んでください。

• 削除または追加されたコントロール、変化した状態、レイアウト密度、並び順、ナビゲーション、目に見えるコンポーネントの置き換えなど、直接比較するとレビューしやすい場合は、Before／After のワイヤーフレームを 1 組使用します。このペアの配置（横並びか縦積みか）は、形状に応じて references/wireframe.md の規定に従います。
• 変更が純粋な追加である場合や、「変更前」の状態を示しても、変更がないこと以外にレビュー上の価値がない場合は、変更後のみのワイヤーフレームを使用します。
• UI の変更がフローに依存する場合、レスポンシブな場合、または状態を持つ場合は、ワイヤーフレームを 2 つより多く使用します。変更前／変更後の 1 組に無理に押し込まず、意味のある状態を順番に示してください。
• メニュー、ポップオーバー、ダイアログ、トースト、パネルなどの小さな画面では、対応する surface（popover、panel など）を使用し、対象のサブ画面に焦点を当ててください。ページ上の配置自体が変更点でない限り、ページ全体を描き直さないでください。

各ワイヤーフレームは、変更された UI の動作、コンポーネント名、ファイルパス、差分から確認できるラベルや状態に基づいて作成してください。正確なピクセル値をキャプチャせず推測した場合は、ワイヤーフレームのキャプションまたは簡潔な注釈にその旨を記載してください。ローカルで手動作成する要約では、ワイヤーフレームを含むプランのソースをインポートまたは更新し、レンダリングされた要約を開いたときに UI の図が表示されるようにしてください。

ワイヤーフレームの品質 — references/wireframe.mdをお読みください

UIの振り返り／計画用ワイヤーフレームは、厳格な品質基準を満たす必要があります。全幅のクローム、下部に固定されたバー、実際のプロダクトコンテンツ、変更前後を比較できる構成、適切なsurfaceプリセット、16 進数カラーの代わりに--wf-*トークンを使用すること、そして<html>／<style>／フォントタグを使用しないことが求められます。ワイヤーフレーム／<Screen>／WireframeBlockを作成する前に、必ずこのスキルディレクトリのreferences/wireframe.mdをお読みください。これはHTMLワイヤーフレームの品質基準に関する唯一の信頼できる情報源であり、/visual-planおよび/visual-recapと一字一句共有されています。記憶を頼りにワイヤーフレームを作成しないでください。

標準のWireframeBlock／<Screen>形式を使用し、Planビューアーにサーフェスのフレーム、テーマ、ラフ／クリーンの切り替えを任せてください。配置の正確さが重要な場合、特にポップオーバー、メニュー、ダイアログ、情報量の多いフォームには、HTMLワイヤーフレームが適しています。HTMLワイヤーフレームでは、デザイン専用の編集可能なモックアップが明示的に必要な場合を除き、renderModeは未設定のままにするか、wireframeにしてください。renderMode="design"を指定すると、ラフなスケッチ風オーバーレイが無効になります。

ブラウザツールが利用できる場合は、UIに影響する振り返りをPlanビューアーでレンダリングし、共有前に現在のテーマで見た目を確認してください。ラベル、注釈、ツールバー、ワイヤーフレームのコンテンツがほかの要素と重なっている場合は、MDXを修正して再インポートしてからリンクを共有してください。レンダリングして確認するのは1回、修正して再レンダリングするのは最大1回までにしてください。ユーザーから明示的に依頼されない限り、それ以上繰り返さないでください。テキスト一致を確認できるスクリーンショットだけでは不十分です。キャプチャした画像を目視で確認してください。ヘッドレスCIエージェントなど、ブラウザが利用できない場合は、その旨を振り返りの引き継ぎに記載してください。

トップキャンバスの振り返り — ../visual-plan/references/canvas.mdをお読みください

振り返りにトップキャンバス、ストーリーボード、またはフロー表示が含まれる場合は、canvas.mdxを作成する前に../visual-plan/references/canvas.mdをお読みください。振り返りのキャンバスアートボードでは、本文用の高品質なドキュメントワイヤーフレームと同じHTMLワイヤーフレームの方式を使用してください。つまり、セマンティックなHTMLフラグメントを使った<Screen surface="..." html={...} />を使用します。キャンバスの<Screen>タグ内に、<FrameScreen>、<Card>、<Row>、<Title>、<Btn>などのキットツリーの子要素を新たに作成しないでください。これらのコンポーネントは古いプランとの互換性を保つためのレガシーマークアップです。新しいキャンバスストーリーボードでは、本文内のワイヤーフレームの見た目が良くても、レイアウトが窮屈になったり、要素が重なったりすることがあります。キャンバスのモックアップが、同じ画面をページ下部に置いた場合より見劣りするなら、レガシーキット方式が使われていると考え、HTML画面に置き換えてください。

要約を開いて共有する

ローカルファイルのプライバシーモードでは、まず plan local check を実行してから、 npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open または <plan-dir>/.plan-url にあるローカルの ブリッジ URL を共有します。これによりホストされた Plan UI が開きますが、 データの読み込み元はこのマシン上の localhost ブリッジであるため、マシン間で共有できません。 同じ PLAN_LOCAL_DIR を使って Plan アプリ自体をローカルで実行している場合は、 /local-plans/<slug> のルートも有効です。ホストされたデータベース URL をでっち上げたり、 絶対 URL の Plan リンクを得るためだけに公開したりしないでください。

要約を作成したら、プランをレンダリングしたページへのリンクを、 プランが実際に保存されているデータベースのオリジン上にある絶対 URL でレビュー担当者に共有します。 そのオリジンは、要約の作成に使用した Plan MCP サーバーです。稼働中だと知っている どの開発サーバーでもよいわけではありません。create ツールが正しいリンクを返すので、 そのリンクを共有してください。メインのリンクとして、ローカルの plan.mdx ファイル、 ローカルのミラーフォルダー、/plans/<id> のような相対パスを使ってはいけません。

プライベートリポジトリの PR に要約を投稿する場合、プランのリンクは公開 URL ではありません。 PR コメントや引き継ぎの文面には、リンクを開くには、所有する組織へのアクセス権を持つアカウントで Agent-Native Plans にサインインする必要がある場合があることを明記してください。たとえば、 「プライベートリポジトリの要約：プランが開かない場合は、この組織へのアクセス権があるアカウントでサインインしてください。」 のように記載します。リポジトリや組織の公開範囲によってアクセスが制限されている場合に、 リンクが壊れている、または公開されていると示唆しないでください。

要約は、作成元の MCP のデータベースにのみ存在します。別途実行中のローカル開発サーバー （例：http://localhost:8081）は独自のデータベースを持っており、ホストされた MCP 経由で 作成した要約は含まれません。そのため、自分で作成した localhost リンクを開くと 「Plan not found」が返されます。これは要約で最もよくある間違いです。MCP のデータを共有していると 確認できていないオリジンを推測してはいけません。

URL は次の順序で解決します。

1. create ツールが返す絶対 URL を使用します。openLink.webUrl、次に返された plan.mdx のフロントマターにある visualUrl、それらがなければ url／path を MCP サーバー自体のオリジンに対して解決します（ホストされた MCP の場合は https://plan.agent-native.com）。これは常にプランが保存されているデータベースを指します。
2. 要約が、同じオリジンにバインドされた Plan MCP 経由で作成された場合に限り、 localhost／開発用オリジンを使用します。つまり、その MCP の URL が http://localhost:<port>/mcp である必要があります。ホストされた MCP 経由で作成して localhost にリンクする不一致が、404 の原因になります。
3. プラン ID しかない場合は、MCP オリジンの絶対 URL を組み立てます （ホストされた場合：https://plan.agent-native.com/plans/<id>）。その URL は推定したものだと伝えてください。

ユーザーが localhost でレビューしたいものの、要約がホストされた MCP 経由で作成されている場合は、 そのことを明確に伝えてください。ローカル開発サーバーからはその要約を参照できません。 localhost で要約を表示するには（例：デプロイ前のローカルレンダラーの変更を試す場合）、 ローカルデータベースに保存されるよう、ローカルの Plan MCP（http://localhost:<port>/mcp）に 接続し、その MCP 経由で要約を再作成する必要があります。解決できない localhost URL を渡すのではなく、 その操作を申し出てください。

Codex で実行中に Browser／アプリ内ブラウザのツールが利用できる場合は、作成後に返された 絶対要約 URL を自動的に開きます。最終回答にも同じ絶対 URL を必ず記載してください。 plans/<slug>/plan.mdx のようなローカルミラーファイルに触れてよいのは、 ソース管理上の補助的な成果物としてのみです。要約を開く主な方法として案内してはいけません。

Diff → ブロックの対応付け

実際の diff に基づき、変更の種類ごとに、その変更を表すブロックを機械的に対応付けます。 以下の名前は概念上のブロック種別であり、JSX タグではありません。作成前に、 「ブロックリファレンス」を参照し、get-plan-blocks ツールを使って、 各概念名を正確なタグと prop スキーマに対応付けてください。

• スキーマ／マイグレーションの変更 → 変更後のエンティティ、フィールド、関連には data-model を使用します。実際のマイグレーション差分に基づき、フィールド／エンティティごとに何が変更されたかを change: "added" | "modified" | "removed" | "renamed" で示します。型が変更された場合は、以前の値（例：変更前のカラム型）を was に設定します。この差分を反映した data-model が主役です。文字どおりの SQL が正確に重要な場合に限り、分割した diff を使用します。既定では使用しません。
• API／アクション／ルートの変更 → 変更後のメソッド、パス、パラメーター、リクエスト、レスポンスを記述する api-endpoint を使用します。変更された各パラメーター／レスポンスに change を付け、型や形状が変わったパラメーターには was も設定します。ルートが完全に追加または削除された場合は、エンドポイントのルートに change を設定します。削除されたエンドポイントには deprecated: true を設定し、説明文でその旨を説明します。 複数の API エンドポイントは、明示的な変更前／変更後のコントラクト比較でない限り、通常の単一カラムのドキュメントフローにまとめます。 リクエスト／レスポンスの各例は、単独で解析可能な有効な JSON 値を 1 つだけ含むように作成します。つまり、トップレベルのオブジェクトまたは配列を 1 つだけ含め、折りたたみ可能な JSON エクスプローラーでレンダリングできるようにします。1 つの例の中に // や /* */ のコメント、説明文、末尾のカンマ、または連結したトップレベルオブジェクトを 2 つ以上含めないでください。解析できない本文はフラットテキストにフォールバックし、エクスプローラーが表示されなくなります。 エンドポイントに複数の異なるメッセージ形式（たとえば、別々の WebSocket フレーム型、または成功時の本文とエラー時の本文）がある場合は、1 つの本文に詰め込まず、それぞれに個別のラベルを付けた例を用意します。
• 互換性に影響する変更 → 関連する data-model／api-endpoint ブロックの横に、簡潔な rich-text の注記を置きます。変更されたフィールド、エンドポイント、または動作を示し、破壊的、リスクあり、または非破壊的のいずれかを明記します。その注記に、変更された行を示す分割 diff を添えます。
• 意味のあるコードハンク → 実際の before／after テキストと filename／language を含む、mode: "split" の diff を使用します。変更前と変更後を読み比べられることが要点なので、変更の概要を示すコードレビューでは分割モードが既定です。左右並列にするとコードが読みにくくなる、真に小規模で独立したハンクに限り、mode: "unified" を使用します。各 diff には、ハンクの変更内容とその理由を示す 1 行の summary を付けます。説明としてコードの上に表示されるため、レビュー担当者が最初に意図を把握できます。ラベルのない diff は残さないでください。 主要な変更ファイルには、重要な各ハンクの内容を要約で示すため、diff に annotations を付けます。変更された主要ファイルに注釈を付けることが、要約で特に重要な機能です。各注釈は既定で変更後の行番号に紐づきます（削除された行を指すには side: "before" を設定します）。1 行ごとではなく、ファイルごとに重要度の高い注記を数件に絞ります。 複数の主要ファイルにそれぞれ大規模な差分がある場合は、markdown が ## Key changes の rich-text 見出しブロックでグループを導入し、横向き（既定値のため orientation は省略）に配置した再利用可能な tabs ブロックの中に diff ブロックを置きます。これにより、選択したファイルの分割 diff がドキュメント幅いっぱいに表示されます。見出しがセクション名を示すため、tabs ブロックには title も設定しないでください。各タブのラベルは、ファイルパスか、ディレクトリのヒントを添えた短いベース名にします。 レンダラーの幅広レイアウトの対象は意図的に限定されています。diff、annotated-code、縦向きの tabs、および diff 系の子要素を含む tabs は、本文よりも幅広く表示されます。幅を広げる目的だけで、API エンドポイント、OpenAPI 仕様、データモデル、JSON エクスプローラー、ワイヤーフレーム、質問フォーム、カスタム HTML を tabs に入れないでください。 要約の末尾に補足的な diff が複数ある場合、末尾の diff 付録は個別の diff ブロックを並べるのではなく、独自の ## Key changes 見出しの下に置く、横向きの tabs ブロック 1 つにまとめます。
• 新規ファイル、または意味のある「変更前」がない大規模な追加ブロック → 片側だけの分割 diff ではなく、annotated-code を使用します。実際に追加されたコードに filename／language を付け、重要な行に重要度の高い注記を数件紐づけます。これにより、レビュー担当者はコードそのものではなく、新しいコードが何をするかを把握できます。削除された行にも意味がある、真の変更前／変更後のハンクには分割 diff を使用します。複数の注釈付きコード解説をまとめる場合も、diff と同様に横向きの tabs ブロックを使用します。
• 追加／削除／名前変更されたファイル → 各エントリに change フラグ（added、removed、modified、renamed）と短い note を付けた file-tree を使用します。パスだけでは伝わらない情報がある場合に限り、snippet を添えます。
• レンダリングされる UI／操作の変更 → レビュー担当者がコードを読む前に、UI の目に見える差分を示すワイヤーフレームを 1 つ以上用意します。比較によって変更が分かりやすくなる場合は「変更前」「変更後」のワイヤーフレームを使用し、そうでない場合は変更後のみ、または短い状態／フローのシーケンスを使用します。実際の UI に即した画面を用意します。ポップオーバーの変更なら、タイトル行、右上のアクション、オプション／フィールド、タブ、選択済み／無効状態、ユーザー／リスト／行、および開いているプロンプト／メニューを正しいトリガーに紐づけて表示します。ルートが追加された場合は、ルートの本文と、差分で実装されている場合は利用不可／空の状態を表示します。権限が変更された場合は、管理者ができることと、閲覧者／非管理者に代わりに表示される内容を示します。 本文は簡潔に保ちます。UI の説明はワイヤーフレームに任せ、実装の証拠はファイルツリーと diff ブロックで示します。
• アーキテクチャまたはデータフローの変更 → 2 パネルの変更前／変更後、レイヤー、またはスイムレーン形式のレイアウトを data.html／data.css で表現した diagram、または簡潔なグラフを mermaid で用意します。二次元のレイアウトを使用し、構造的な変更を左から右への単純な連鎖にしないでください。レンダリングされる UI コントロールの代わりに diagram を使用しないでください。UI の変更には wireframe ブロックが必要です。 ダイアグラムの HTML／CSS には、レンダラーが提供する .diagram-panel、.diagram-node、.diagram-pill、[data-rough] などの .diagram-* プリミティブと、references/wireframe.md で定義されている同じ --wf-* テーマトークンを使用します。font-family、16 進数、rgb／hsl のリテラル、または独自のダーク／ライトパレットは使用しないでください。外枠の frame は意図的に選びます。要約のダイアグラムは単独で表示する場合、通常は frame: "show" が適していますが、カラム、タブ、カード、またはダイアグラム自体のパネルがすでに境界を示している場合は frame: "hide" を使用します。
• 成果を先に示すナラティブ → 「何が変わり、なぜ変わったのか」を説明する文章には rich-text を使用します。差分の目的、差分に表れている重要な判断、レビュー担当者が考慮すべきリスクを説明します。モデルが自由に文章を書くのはここだけです。

ブロックリファレンス — タグを暗記せず、get-plan-blocks を呼び出してください

上記の概念上のブロック名（api-endpoint、data-model、json-explorer、 tabs、…）は、記述する JSX タグではありません。また、正確なタグ、必須フィールド、 プロパティの形式は、ブロックライブラリの進化に伴って変わります。暗記したタグを 使って記述しないでください。タグは変更され、誤ったタグ（Endpoint ではなく ApiEndpoint、Json ではなく JsonExplorer、TabsBlock ではなく Tabs）が インポート時にエラーを起こさずに生成されることがあります。

構造化されたプランの内容を書く前に、ブロックカタログを取得または読み込んでください。 ホスト型またはセルフホスト型のモードでは、Plan MCP コネクターの get-plan-blocks（plan またはレガシーの agent-native-plans）を呼び出します。 遅延読み込み方式のクライアントで Plan ツールがまだ表示されていない場合は、まずホストの ツール検出機能（利用可能な場合は tool_search）を使って検索・読み込みます。 ローカルファイルモードの場合、またはスキルがプレーンテキストとしてインストールされ、 検出後も MCP ツールが登録されていない場合は、npx @agent-native/core@latest plan blocks --out plan-blocks.md を実行し、そのファイルを先に読み込みます。CLI コマンドは、認証不要で公開されている get-plan-blocks ルートを呼び出し、プランや要約の内容は送信しません。ネットワークに アクセスできない場合は、同梱のリファレンスを使い、plan local check で検証してください。 ホスト型の Plan UI にアクセスできる場合、またはローカルの Plan アプリがすでに実行中の 場合に限り、plan local serve を実行してください。

カタログには、アプリ独自のブロックレジストリからリアルタイムに生成された、正式かつ 常に最新のブロック用語が返されます。これは、レンダラーと MDX のラウンドトリップが 使用するものと同じ設定であるため、この SKILL.md が古いインストール済みコピーでも 古くなることはありません。

• get-plan-blocks（デフォルトの format: "reference"）→ 各ブロックのランタイム type、正確な MDX <Tag>、配置、主要なデータフィールドをまとめた表です。上記の 各概念名を実際のタグとプロパティに対応付けるための一覧です。
• get-plan-blocks に format: "schema" を指定 → 各ブロックの完全な JSON Schema と、 そのブロックの記述例が返されます。フィールドの正確な型、列挙値、ネスト構造が必要な 場合に利用してください（例：Diff.annotations、Endpoint.params[].in、 DataModel.entities[].fields[]）。

この呼び出しで返されるタグとスキーマに基づいて、要約のソースを記述してください。 有効なブロックレベルのタグは、get-plan-blocks に列挙されたものがすべてです。 それ以外の大文字で始まるタグは、インポート時に「Unknown plan block」／「did you mean」 エラーで拒否されます。rich-text／Markdown の文章内にある小文字の HTML タグ （<div>、<span>、<code>、<br>、…）は常に使用できます。検証されるのは、 大文字で始まるコンポーネント形式のブロックタグだけです。

レジストリの表では示せない、要約の記述に関する固有のルールがいくつかあります。

• すべての構造化ブロックには REQUIRED の id（プラン全体で一意）と、共通の任意の summary / editable エンベロープが必要です。通常のトップレベルの Markdown 散文は自動的にリッチテキストとしてインポートされます。散文に明示的なメタデータが必要な場合、または参照されるブロック ID を保持する必要がある場合にのみ <RichText id="..."> を使用してください。
• 大文字で始まるすべてのブロックコンポーネントは、自己終了（<Diagram ... />）にするか、子要素を明示的に囲んで閉じる（<RichText ...>...</RichText>）必要があります。段落内に <RichText ...> のような裸の開始タグを残さないでください。MDX はこれを閉じられていない JSX として扱い、recap がレンダリングされる前にインポートが失敗します。
• コードを含むブロック（Code、AnnotatedCode、Diff）は空白に敏感です。複数行のコードが code={"const x =\n y"} のような JSON 文字列属性としてエンコードされている、get-plan-blocks の例 / ソースエクスポーターの正確な MDX 形式を優先してください。静的テンプレートリテラルは、${...} 補間のない静的文字列である場合にのみ受け入れられます。
• Endpoint: 散文の description は MDX の children（タグ間の本文）であり、属性ではありません。WebSocket アップグレードには method="GET" を使用します。各リクエスト/レスポンスの example は JSON 文字列です（レンダラーがそれを JSON エクスプローラーにパースします）。そのため、単一のパース可能な JSON 値に保ってください。
• TabsBlock: tabs 配列全体（ネストされた子ブロックを含む）は 1 つの JSON tabs={[…]} prop です — ネストされた <Tab> 要素はありません。
• WireframeBlock: その本文は単一の <Screen surface ... html=… /> サブツリーです（フラットな prop ではなく、ネストされた MDX）。html は単一引用符の文字列または静的テンプレートリテラルでなければならず、動的な html={someVar} 式にしてはいけません。HTML のルールについては references/wireframe.md を参照してください。
• Diagram: ペイロード全体は 1 つの data={{ html?, css?, nodes?, edges?, … }} 属性であり、html または少なくとも 1 つのノードが必要です。Mermaid はそれ自体が独立したブロック（source テキスト）であり、Diagram の prop ではありません。

Before / After が見出しです

要約の中心となるのは、変更前と変更後の比較です。ドキュメント本文の比較には2つの基本要素があり、組み合わせることで必要な比較をすべて網羅できます。

• columns — 横並びのコンテナーです。構造化された比較に使用します。Before と After というラベルを付けた2つの列を用意し、それぞれにブロック（通常は data-model、api-endpoint、または rich-text）を配置すると、レビュー担当者は新旧の形を一目で比較できます。「スキーマがXからYに変わった」や「エンドポイントの契約がこのように変わった」という場合に適した基本要素です。APIエンドポイントのリストを単にコンパクトにまとめたりグループ化したりする目的で、columns を使用しないでください。
• diff — コードに使用します。削除された行と追加された行をそのまま表示します。実際の差分の塊にはこれを使用してください。要約でコードをレビューする場合は、デフォルトで分割モードを使用します。mode: "unified" は、横並びにするとコードが見づらくなる、本当に幅の狭い単独の差分の塊に限って使用してください。主要ファイルの差分グループには横タブを使用し、分割差分がドキュメントの幅を最大限使えるようにしてください。

UIの差分では、ワイヤーフレームが視覚的な比較の基本要素です。比較によって変更点が明確になる場合は変更前と変更後のワイヤーフレームを使用し、変更内容により合っている場合は変更後のみ、または状態の遷移を使用してください。抽象的な説明に入る前に、視覚的な見出しで正確な配置、現実的なUIの外枠、十分なパディングを示す必要があります。差分によってフローが追加される場合、最初に見える操作要素だけで終わらせず、レビュー担当者が実際のユーザーの操作経路をたどれるよう、入口、開いた画面、そして結果の状態またはページを示してください。変更前と変更後のレイアウトの選択については、references/wireframe.md に従ってください。columns レンダラーは幅の狭い画面を横並びに保ち、幅の広い desktop／browser フレームは自動的に縦に並べます。custom-html でワイヤーフレームを手作業で横並びに配置してはいけません。ドキュメント本文の比較には、他に複数列を扱う基本要素はありません。columns と diff ブロックが、比較に使える要素のすべてです。custom-html で横並びのレイアウトを手作業で作成してはいけません。また、columns を使えば data-model ブロックを横並びにできるのに、2つを縦に積み重ねて比較として扱ってはいけません。

根拠に基づくルール

構造化ブロックが構成上正確であると言えるのは、実際に変更された行から作成されている場合に限ります。diff、data-model、api-endpoint、file-tree ブロックは、実際の差分から機械的に構築しなければなりません。実際のパス、実際のフィールド、実際のメソッド／パス、実際の変更前後のテキストを使い、推測、丸め、捏造は決して行わないでください。モデルが書くのは説明文だけです。「理由」、経緯、リスクの評価を記述します。レビューの場で自信に満ちた誤った要約を示すのは危険です。要約を信頼したレビュー担当者が、要約の誤りの原因となった行そのものを見落とす可能性があるためです。差分に記載のない事実は推測せず、省いてください。モデルが推論した事柄（抽出した事実ではないもの）は、説明文の中で推論であることを明記してください。

セキュリティ

• 閲覧範囲を制限する。 プライベートリポジトリの要約は、組織またはログインユーザーによる認証を必須にしてください。プランの公開範囲を所有者である組織またはログインユーザーに設定し、自動的に公開しないでください。要約によって未公開のスキーマ、内部エンドポイント、アーキテクチャが漏れる可能性があります。要約は、要約元のソースと同じように扱ってください。要約へのリンクが開けない場合、リンクを含むPRコメントや引き継ぎには、プライベートリポジトリの要約を閲覧するには、所有者である組織へのアクセス権を持つアカウントでサインインする必要があることを明記してください。
• シークレットを転記しない。 差分には、APIキー、トークン、Webhook URL、署名用シークレット、.env の値、または認証情報と思われるリテラルが含まれている可能性があります。これらを diff、file-tree のスニペット、api-endpoint、または説明文ブロックにコピーしないでください。必ず伏せ字（sk-•••、<redacted>）にしてください。これは、リポジトリのハードコードされたシークレットに関するルールに準じるものです。あらゆるブロック、キャプション、注記には、明らかに偽だと分かるプレースホルダーのみを使い、実際の値は決して含めないでください。

双方向のループ

ホストモードでは、リキャップは実際に編集できるプランであるため、フォワードプランと同じレビューループが適用されます。レビュアーは任意のブロックに注釈を付けることができ、コーディングエージェントは get-plan-feedback を読み取ってコードの修正につなげます。これは、注釈 → エージェント → 差分という、フォワードプランで使われるものと同じ、ループを完結させるフローです。レビュアーがブロックに注釈を付けたら、get-plan-feedback を呼び出して構造化されたフィードバックを読み取ります。その後、既存の planId を渡して create-visual-recap でリキャップを更新して置き換えるか、update-visual-plan で対象を絞って変更を適用します。このループは稼働しており、接続済みです。ローカルファイルのプライバシーモードでは、これらのホスト型ツールを呼び出さないでください。チャットまたはローカルファイルからレビューのメモを読み取り、<plan-dir>/*.mdx を直接編集してから、<plan-dir> に対して plan local check、serve、または verify を再実行してください。まだ自動化されていないのは、PR コメントを契機とする再実行です。GitHub Action は各 PR に初回のリキャップを作成しますが、GitHub に新しいレビューのフィードバックが投稿されても、まだ自動で再実行されません。この自動再実行が、今後対応する残りの機能です。

関連スキル

• visual-plan — 共有されるワイヤーフレーム＆キャンバスおよびドキュメント品質の中核を定義する、標準のコマンドおよび情報源です。リキャップは同じブロックの規律に従い、逆方向に進みます。
• comment anchors — リキャップのコメントには、フォワードプランと同じアンカールールが適用されます。座標系、ワイヤーフレームのノード ID、テキスト引用の解決、切り離されたスレッド、resolutionTarget によるルーティング、消費済み／解決済みの二軸状態については、visual-plan スキルの「コメントアンカーの解釈」を参照してください。
• security — リキャップの編集・表示制御の基準となっている、データのスコープ設定、シークレットの取り扱い、ハードコードされたシークレットに関するルールです。
• sharing — リキャップを保持するプランの表示範囲を、組織／ログイン状態に応じて制御します。