explain-diff

name	explain-diff
description	コード変更・diff・ブランチ・PRについて、リッチでインタラクティブな解説を生成するスキル。「この変更を解説して」「このPRを説明して」「diffを分かりやすくまとめて」「このブランチの変更点を教えて」「変更内容の解説ページを作って」と言われたら使う。背景・直感・コード・批評・クイズの5セクションから成る自己完結HTMLファイルを出力する。解説だけでなく批判的な視点も含む。他人のPRや自分の変更を、初学者にも分かる形で理解・共有したい場面で積極的に使うこと。
argument-hint	[diff / ブランチ名 / PR番号など解説対象]
ref	https://gist.github.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524

Explain Diff

指定されたコード変更について、リッチでインタラクティブな解説を作る。

以下のセクションを含めること:

• Background（背景）: この変更に関連する既存システムを説明する。（そのために周辺コードを広く探索すること。）読者がどれだけ知っているか分からないので、初学者向けの深い背景を含めた上で（既に詳しい読者はスキップできる旨を明記）、続けて変更に直結する狭い背景を説明する。ただし「前提知識のレベル合わせ」でスキルが既知と判断した／ユーザーが既知と答えたキーワードは深掘りを省き、未知のものに紙面を割く。

• Intuition（直感）: コード変更のコアな直感を説明する。ここでのフォーカスは細部ではなく本質を伝えること。トイデータを使った具体例を用いる。図やダイアグラムを積極的に使う。

• Code（コード）: コードへの変更点を高レベルにウォークスルーする。変更を理解しやすい形にグループ化・順序付けする。

• Critique（批評）: PRの方向性や実装が正しいことを前提にせず、率直な批評家として問題点を指摘する。ここまでのセクションが「この変更をどう理解するか」だとすれば、ここは「この変更は本当に良いのか」を問うパート。以下の4観点を必ずカバーする（各観点で指摘がなければ「特になし」と明記し、無理に難癖はつけない）:

  • 設計・代替案: アーキテクチャの妥当性、別のアプローチの可能性、過剰／不足な抽象化。「なぜこの方向を選んだのか」「もっと単純な方法はなかったか」を問う。
  • バグ・エッジケース: 見落とされた境界条件、潜在的な不具合、エラーハンドリングの漏れ。可能なら具体的な再現シナリオを示す。
  • 保守性・可読性: 命名、複雑さ、将来の変更のしやすさ、技術的負債。
  • テスト・スコープ: テストの過不足、PRのスコープが適切か（やり過ぎ／やり足りない）。

  批判は必ずコード上の具体的な根拠に紐づける。感想や一般論ではなく「この関数のここがこうだから」という形で書く。ただし解説者はPRの背景・議論・制約をすべて知っているわけではないので、断定できない指摘は確信度と前提を明示する（例:「〜という前提が正しければ、これは問題」）。読者が批評を鵜呑みにせず自分で判断できるようにするのが目的。

• Quiz（クイズ）: このPRの理解度を測る問題を5問作る。中難度にすること。実際に内容を理解していないと解けない程度に難しく、ただし引っかけ問題にはしない。目的は読者が本当に理解できたかを確認する手助け。インタラクティブな選択式問題として提示し、クリックすると正誤とフィードバックが表示されるようにする。

前提知識のレベル合わせ（在席なら質問、放置なら自動進行）

読者がどこまで知っているか分からないまま書くと、背景説明が厚すぎたり薄すぎたりする。そこで生成の前に、ユーザーがその場にいれば前提知識を軽くすり合わせ、放置していれば待たずにデフォルトで完成させる。この2モードを待機時間で自動的に切り替える。

手順:

1. 調査を先に済ませる。 diff・周辺コード、PRなら議論まで。この段階を飛ばして質問しない。
2. 既知/未知はまずスキル側で判断する。 一般教養レベル、あるいはそのコードベースを触る人なら当然知っているもの → 既知扱いで背景を軽く流す。マニアックすぎて誰も知らないもの → そもそも列挙しない。この自動判断で大半のキーワードは処理しきる。
3. 本当に判断が割れる少数（多くて数個）だけをユーザーに確認する。「この読者が知っているか、こちらでは読めない」ものに限る。判断が割れるものが1つも無ければ、質問自体を省いて即デフォルトで生成してよい。
4. 確認はテキストで番号付きリストとして提示する。AskUserQuestionは、後述のタイマー自動進行と両立しないので使わない。メッセージには「既に知っている番号だけ返してください。5分以内に返答がなければ、前提ありありのデフォルトで生成して完成させます」という主旨を必ず含める。短く、気軽に番号を返すだけで済む形にする。
5. 質問を出したら ScheduleWakeup を delaySeconds: 300 でセットしてターンを閉じる。
   • 5分以内にユーザーが返答したら: その回答を反映し、選ばれた＝既知の背景を削り、未知に紙面を割いて生成する
   • 5分経っても無反応なら: wakeup が発火するので、そこでそのままデフォルトで最後まで生成しきる。 もう質問しない。

フォーマット

• CSSとJavaScriptを含む単一の自己完結HTMLファイルを出力する。全体を1本の長いページにし、セクション見出しと目次を付ける。トップレベル構造にタブUIは使わない。スマホで見られる程度の基本的なレスポンシブスタイルもあると良い。ファイルは特に指示がなければコードリポジトリの外のグローバルな場所に置き、ファイル名は必ず今日の日付を YYYY-MM-DD- 形式で先頭に付ける（時系列でソートされ、バージョン管理から外れるため）。例: /tmp/2026-01-12-explanation-<slug>.html

• Martin Kleppmann のような明快さと流れで書くこと。読ませる文章、古典的なスタイルで。セクション間の遷移はスムーズに。

• 図についてのヒント。理想的には、解説全体で使い回せる少数の図のファミリーを選び、様々なケースの説明に再利用する。有用な図の種類:

  • アプリでユーザーが見るUIのごく簡略化した版。UI変更の説明に使う。
  • コンポーネント間のデータフローや通信を示すシステム図。ここには必ず例となるデータを含めること。

• ASCIIアートの図は使わない。図はシンプルなHTMLで作り、リストはHTMLのリストで作る。

  • コードブロックには必ず <pre> タグを使う。カスタムスタイルの div を使う場合は、CSSに 必ず white-space: pre-wrap を含めること。含めないとブラウザが改行をすべて1行に潰してしまう。ファイルを保存する前に、HTMLソース内の各コードブロックをスキャンし、CSSに white-space: pre または pre-wrap が含まれていることを確認する。

• 重要な概念や定義、重要なエッジケースなどには callout（囲み）を使う。