explain-visually

視覚的に説明する

目的：読者が、何が変わるのか、どのように、なぜ動作するのかをすばやく理解し、コードのすべての行を読まずに判断できるようにします。説明するより、見せることを優先します。まずは簡潔に、詳細は必要に応じて示します。1ページ、約1,000～1,500語： 短いストーリー形式の手順と、判断に必要な詳細を選択肢の行や切り替え項目に示します。

事実をそのまま伝え、特に見出しでは正確に表現します。

• 「移行済み」は「維持」や「動作中」を意味しません。「尊重」は「変更なし」を意味しません。例外は同じ文で明記します： 「263個のルールは移行されます。1つは無効にする必要があります」。
• 条件を変えて測定した数値を「同じ」と表現してはいけません：「そのルールを無効にした後で5.3秒」。
• 一部のメンバーに当てはまることを、グループ全体に当てはまるように書いてはいけません。対象を明記します（「react-xとreact-jsxはプラグインとして読み込まれます」）。
• ツールに初めて触れる読者を想定し、ストーリーでも選択肢の行でも、ツールや用語が最初に登場する箇所で、同じ文の中に短い説明を添えます（「tsgolint（Oxcの型チェック用ヘルパー）」）。

見た目はexplainer-kitスキルに従います。各章はそれぞれのexplain-with-*スキルに従います。

このスキルを使う場面

• ユーザーが視覚的な説明、解説、または「これを視覚的に説明して」と依頼した場合。
• ユーザーが十分な情報に基づいて判断できるよう、コードの変更、提案、計画、アーキテクチャ上の決定を説明する場合。

1. 情報と事実を収集・調査してfacts.mdにまとめる

• 事実をまとめたファイルがすでにある場合（例：タスクで提供されている場合）、それを信頼できる情報源として使い、ステップ2に進みます。
• 最大3つのサブエージェントを同時に使って、事実やトピックを調査します。
  • 各事実は、出典（file:line、リンク、または実行したコマンド）とともに1行で記録します。考えている途中で事実を言い直さず、一度だけ書きます。
  • 数値は手作業で数えず、コマンド（grep -c、jq、計測実行など）から取得します。
  • 手間がかからない場合は、実際のリポジトリで測定します（スクラッチコピーまたはワークツリーを使い、リポジトリ自体は使いません）。測定方法とバージョンを記録します。「すべて」や「常に」と言えるほどの根拠がない限り、測定結果を一般化してはいけません。
  • 予算：これから述べるすべての主張に出典が得られた時点で終了します。
• オーケストレーターとして、調査内容をfacts.mdにまとめます。
• ユーザーが決める必要のあること、選択肢ごとの作業量、対処法を含むリスク、推奨内容を変える条件を記録します。

2. ページを計画する（独立した概要は作らない）

notes.mdの最初の行に計画を書きます（15行以内）。1文で答えと主なコストを示し、主要な数値を3～5個（それぞれページ内の掲載箇所は1か所だけ）、説明する用語を4～8個、実際に示すコード断片を1つ（読者が変更する設定またはコード、8行以内）、各章を1行ずつ記します。章は次のとおりです：

章	使用するもの	セクション	使用する場面
概要	このスキル（キットの概要）	—	常に
ストーリー	explain-with-storytelling	story	常に：5～7ステップ、変化していく図を1つ
コード	explain-with-code-walkthrough	code	読者が確認すべき変更がコードそのものである場合のみ
判断	explain-with-preview、選択肢（JSON）	decide	ユーザーに判断してもらうことがある場合

• 概要の後に加える章は最大3つです。脆弱性、依存関係、複雑さは独立した章にせず、判断用の選択肢の行（維持するもの／失われるもの／最初に直すこと／リスク）に記載します。変更前後を比較する独立した章（explain-with-preview）を設ける場合は、判断が不要であることを条件にコード章の代わりとします。
• explain-with-section-clips、-slides、-videoを追加するのは、ユーザーから依頼された場合のみです。
• **概要：**答えと主なコストを示す見出し（「lintが44秒から5.3秒に短縮、1つのルールと3つのチェックを移植」）、1文、ヒーロー要素を1つ（比率を保ちます。数値には、スマートフォンでも読みやすいキットのHTMLev-bars ev-bars--heroを使います）、主要な要点を1行（「判断」コールアウトは最大1つ）で構成します。情報ボックスをグリッド状に並べてはいけません。

3. 章を自分で作成する

• explainer-kit/assets/FRAGMENT-CONTRACT.md と使用する章のスキルを、すべて1回のターンで読みます。このページでは、この契約がAPIのすべてです。kit.css、kit.js、assemble.py、SCRIPTS-AND-TABS.md は絶対に読まないでください。
• 章は自分で1ファイルずつ順番に作成し、それぞれWriteツールを使います（シェルのヒアドキュメントは使わないでください。引用符が1つでも余分にあるとコマンド全体が失敗し、すべてのファイルを書き直すことになります）。この規模のページでサブエージェントを起動しないでください。
• キットのコンポーネントをそのまま使います。新しいテーマ、フォント、コンポーネントや独自のレイアウトCSSは追加しないでください。
• 計画にある実際のスニペットを、意思決定JSONの推奨オプションのcodeとして表示します（設定が変わる場合は、慎重なオプションのものも表示します）。独立した章としては作成しないでください。
• 参照情報は詳細に記載します。ファイルパスはコードヘッダーに、リンクは意思決定の「Sources」トグルに記載します。

4. 組み立てて一度確認し、公開する

python <kit>/assets/preview.py decide.json --out frag-decide.html
python <kit>/assets/assemble.py --page --toc --title "Short name" --overview overview.html \
  --section story=frag-story.html --section decide=frag-decide.html --out index.html
python <kit>/assets/check.py index.html

• すべてのファイルの書き込みが完了してから、これらを1つの連結コマンドとして実行します。
• アセンブラーが報告する契約上のエラーを修正します。
• check.pyを1回実行します。表示された問題だけを修正して、もう1回実行したら終了します。他の問題を探すためにスクリーンショットを撮影・調査したり、独自のブラウザースクリプトを書いたりしないでください。
• ページの文章を一度、facts.mdと照合します。件数、名前、事実で裏付けられていない「すべて／あらゆる」がないか確認します。
• 特に指示がない限り、単一ページをアーティファクトとして公開します。返信は最大5行で、回答、ページのパス、未確認事項を記載します。