html-explainer

HTML 解説

モデルを選ぶ前にブランチを選択してください。割り当てられた役割に応じて、根拠を集め、組み立て、検証し、視覚的な成果物を確認してください。独立した調査資料の作成担当者に依頼する前に、shared/references/model-preview.md を通じて、承認済みスナップショットを正確に1つ取得するか、既存のものを再利用してください。

実際のシステムの仕組みを、リポジトリの実際のコードに基づいて読者に説明する、自己完結型の HTML ファイルを1つ作成してください。

成果の軸

• 成果物： 主題を3つの深さで説明する、インライン CSS、JavaScript、SVG を含む単一の .html ファイル。
• 次の利用者： ファイルをブラウザーで直接開くユーザーとそのチームメイト。サーバーもビルド手順も必要ありません。
• 完了条件： 合意したパスにファイルが存在し、scripts/validate_explainer.py が終了コード 0 で終了し、ファイルがユーザーに届けられているか、レンダリングされていること。
• 意図： すべてのコードスニペットが実際のものなので、このページは信頼できます。読者は path:line のバーを使って、リポジトリ内の該当箇所に移動できます。

すべてを規定する2つのルール

• 逐語的でなければ掲載しない： すべてのコードスニペットはリポジトリから逐語的にコピーし、path:line の範囲を付記してください。そうでなければページに掲載しないでください。記憶を頼りにコードを再構成してはいけません。短縮する場合は、ソースのバーに (abridged) と記し、行単位で削除してください。主張をファイルで裏付けられない場合は、スニペットを付けずに文章で述べるか、削除してください。
• 掘り下げ契約： ページは3つの深さで機能する必要があります。一目で把握（クリック可能な全体像マップと各セクションの導入段落）、ざっと確認（セクションの要約、表、図）、詳細を確認（コードを含む展開可能なパネル）。重要な情報を詳細確認の深さだけに置いてはいけません。概要部分に大量の情報を詰め込んではいけません。

ワークフロー

1. 範囲の決定

主題（1つのサブシステム、サービス、またはフロー。無関係な主題は別々のページに分ける）、対象読者、そしてページで答えるべき質問を明確にします。

対象読者を1つ選んでください。_初めての人_には全体像と平易な導入が必要です。_実装者_には拡張ポイントと規約が必要です。_レビュアー_には境界、不変条件、依存関係の方向性が必要です。この主題について既に概要ページがある場合は、範囲や根拠を再調査するのではなく、それらを再利用してください。

ユーザーが「X の仕組みを説明して」とだけ依頼した場合のデフォルトの質問セット：アーキテクチャ、使用技術とそれぞれのコード上の配置場所、エンドツーエンドのデータフロー（入力 → 出力）、認可／テナント管理、ログ記録／可観測性。ユーザーが指定した追加事項も反映してください。

デフォルトの出力パス：プロジェクトのリポジトリ内の docs/<topic>-explainer.html。成果物の更新を明示的に依頼された場合は、指定された範囲の編集が許可されます。既存の出力先を置き換える対象として選択していない場合は、新しいパスを使うか、更新する成果物を確認してください。無関係な内容は保持してください。

2. 根拠の確認

根拠に関するルールは shared/references/grounded-evidence.md にあります。それを読み、HTML を作成する前に、その定義に従ってサブシステムごとに根拠資料を作成してください。根拠資料には、仕組み、正確な path:line を示した逐語的なスニペット2～5個、注意事項、コードコメントに記された実例を含めます。

一般的な分解方法（主題に応じて調整してください）：エントリーポイント／インフラストラクチャとデプロイ、主要な処理パイプライン、データアクセスと安全機構、可観測性／ログ記録。サブシステムが独立しており、内容に十分な根拠が必要な場合にのみ、根拠資料の作成を依頼してください。選定した各担当者には承認済みスナップショットを使ってください。入れ子になった担当者は、ルートを再解決したり、別の担当者を追加したりしてはいけません。それ以外の場合は、3段階のページに実際に必要な範囲に限り、自分で調査してください。計画した各セクションについて、導入文、図に必要な事実、スニペット2～5個が揃ったら、読み進めるのをやめてください。

根拠資料の構成は信頼してかまいません。ただし、掲載するスニペットには「逐語的でなければ掲載しない」というルールが適用されます。言い換えられているように見えるスニペットは、掲載前にファイルと照合してください。

3. 組み立てる

このスキルのディレクトリにある assets/template.html を出力先にコピーし、プレースホルダーの箇所を置き換えます。自己完結性、3 つの深さ、エスケープ、検証について、まず shared/references/html-page-conventions.md を読んでください。次に、各スロット、SVG 図の仕組み、スニペットのエスケープ規則について、references/page-anatomy.md を読んでください。

順序に関する重要事項：

• 全体像を示すマップを最初に配置し、各主要ボックスには、実在するセクション ID を指す onclick="jump('sec-…')" を設定します。
• セクションは番号を付け、発見した順ではなく、データの流れに沿って（エッジ → 内部 → データ → 横断的な関心事）並べます。
• すべての .code ブロックに、リポジトリ相対の path:line を記載した .code-src バーを付けます。
• スニペットのテキストでは &、<、> をエスケープします。特に TypeScript のジェネリクスは見落とされやすく、Promise<Foo> は Promise<Foo> にしないと、ブラウザーに黙って無視されます。

4. 検証する

決定的なチェックを実行します。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
python3 "$SKILL_DIR/scripts/validate_explainer.py" <output-file.html>

終了コードが 0 になるまで、指摘された箇所を修正します。その後、ブラウザーを利用できる場合はファイルをレンダリングし、共有規約の検証手順に従って、全体像を示すマップが描画されることと、jump() のクリックで該当セクションが開くことを確認します（最初の画面より下では、スクリーンショットではなく DOM クエリーを使用します）。

5. 提出する

ファイルをユーザーに送信／表示します。要約の冒頭にファイルパスと移動方法（マップをクリック、パネルを展開）を記載し、各セクションを 1 行ずつ列挙します。視覚的に検証できなかった箇所があれば、明記します。

注意点

• path:line のない資料スニペットは、言い換えの疑いがあります。ファイルを読み直すか、そのスニペットを削除してください（原文どおりに記載するか、記載しないかのどちらかです）。
• シークレット、実際に稼働中のホスト名、管理対象／編集済みの内容には、共有エビデンス契約の §6 がそのまま適用されます。シークレットの名前と解決場所を記載し、コードベース独自の編集方針に従ってください。
• セクション数を増やすばかりで内容を深めない構成は避けてください。番号付きセクションは 6～9 個が上限です。それを超える場合は、ページを統合または分割してください。