readout

リードアウト

リードアウトは、調査を耐久性のある HTML ドキュメントへと変換するものです。そのドキュメントは、元のコンテキストが一切なくても、誰かが数週間後に読むことができます。始まり方は次の 2 つのうちのいずれかです。

• スナップショットモード — 会話の途中で呼び出します（「これを書き上げて」）。会話で蓄積された調査結果が素材となります。
• リサーチモード — 新規に呼び出します（「/readout on how github webhook events are processed in the server」）。採掘すべき会話が存在しないため、調査そのものが作業の一部となります。

どちらの場合でも、このスキルの呼び出しはサイドタスクです。メインエージェントとしてのあなたの仕事は、スコープを研ぎ澄まし、良いブリーフを添えて子エージェントを起動し、あとは手を引くことです。子エージェントが採掘・リサーチと執筆を行い、その（しばしば大量の）作業をあなたのコンテキストウィンドウの外に保ちます。

オーケストレーターのワークフロー

1. スコープを研ぎ澄ます — 起動する前に質問する

曖昧なブリーフは曖昧なドキュメントを生みます。起動する前に、そのドキュメントが答える具体的な問いを列挙できるはずです。できない場合は、まずユーザーにインタビューしてください。

• 2〜4 個の的を絞った質問をし、開かれたプロンプトではなく具体的な選択肢を提示します。選択肢が実際のものになるよう、まずコードやトピックをざっと見てください（サブシステム、エントリーポイント、競合する関心事など）。「/readout on how github webhook events are processed」の場合：どの方向が重要か — インバウンドのトリガーか、ポストバックか、その両方か？ 現状のリファレンスか、落とし穴の探索か？ どのリポジトリか？
• 常に深さと読み手を明確にします。高レベルなオリエンテーションか、行レベルの根拠を伴う深いメカニクスか。個人的なメモか、チームと共有するものか。
• 肩をすくめる反応は尊重します。「とりあえず高レベルな概要で」は有効な答えです — それをブリーフに記録して先に進み、問い詰めたりはしません。それでも、読み手が最も答える必要のある 2、3 の問いを引き出そうと努めてください。具体的であることがリードアウトを有用にするからです。
• スコープがすでに具体的な場合はインタビューを省きます — 焦点の定まった会話のスナップショットや、正確なリサーチ依頼には質問は不要です。スナップショットモードでは通常、会話が問いを提供します。呼び出しがどのスレッドを含めるかについて曖昧な場合にのみ尋ねてください。

2. ブリーフを作成する

短いブリーフ（およそ 10〜20 行）を書き、ペイロードではなくポインターを載せます。

• 作業タイトル / トピック、およびモード（スナップショットまたはリサーチ）
• ドキュメントが答えなければならない具体的な問い（会話またはインタビューから）、加えて深さと読み手
• スコープ：どのスレッド / サブシステムを扱うか、および明示的に除外するもの
• スナップショットモード：ドキュメントの中心とする価値のある主要な結論を 1 行ずつ — 子エージェントは会話履歴から完全な内容を自分で引き出すので、調査結果を丸ごと貼り付けないこと
• リサーチモード：開始のポインター — すでに知っているエントリーポイントのファイル、シンボル、ディレクトリ
• 作業の根拠となるリポジトリ / ディレクトリへの絶対パス
• 判明している場合は各リポジトリのホスト URL と調査対象のコミット（例：github.com/org/repo @ abc123）。これによりドキュメントがコード参照にハイパーリンクを張れるようになります

3. ローカル子エージェントを 1 つ起動する

run_agents を介して子エージェントをちょうど 1 つ起動し、ローカル実行とします。ローカルが重要です。ドキュメントはユーザーのファイルシステム上に配置され、ユーザーのブラウザで開かれるからです。子エージェントには readout-<topic-slug> と名前を付けます。

子エージェントのプロンプトは以下のテンプレートから組み立てます。そこには次を含める必要があります。

• ブリーフ
• モードに合った素材のブロック（スナップショットモードではさらに、あなたのエージェント実行 ID — オーケストレーションランタイムコンテキストの current_run_id — も必要です。これにより子エージェントが search_conversation_history で親の会話を採掘できます）
• 執筆の前に、このスキルのディレクトリにある references/doc-guide.md を読むという指示
• 出力パスの規約と完了プロトコル

4. 作業に戻る

起動後は、それまで行っていた作業を再開するか、ターンを終了します。子の完了メッセージは自然に届きます。届いたら、ファイルパスを一行の説明とともにユーザーに伝えてください。リサーチモードでは、新しい会話に他に保留中のものがない場合があります。その場合は単にターンを終了してください。ユーザーがドキュメントを待つように指示した場合を除き、待機ループにとどまらないでください。

子エージェントのプロンプトテンプレート

これを調整して使用してください。構造は維持し、モードに合ったソース素材のブロックを含めてください。

You are producing a "readout": a single self-contained HTML document that answers a
specific set of questions about <topic>, for a reader who has none of this context.

Brief:
<brief — including the questions to answer, depth, and audience>

Source material (snapshot mode):
- The parent conversation: agent run ID <current_run_id>. Use search_conversation_history
  with agent_run_id set to that ID. Make several targeted queries — one per question in
  the brief — rather than one broad query; targeted queries surface far more usable detail.
- The codebase(s) at <absolute paths>. The conversation is your starting point, not a cage:
  verify file references before asserting them, and where a section needs more depth to
  stand on its own, go read the code and fill the gap.

Source material (research mode):
- Investigate directly in the codebase(s) at <absolute paths>. Let the brief's questions
  drive the investigation: trace the actual code paths, read the real implementations, and
  ground every claim in file:line references. Distinguish verified from inferred. Do not
  pad the document with generic knowledge — its value is what's true of THIS codebase.

- Repo host + commit for linked code references, if known: <github.com/org/repo @ commit>
  (otherwise derive from git; see the doc guide's "Linked code references").

Start from the canonical template at <skill-directory>/assets/template.html — its
data-readout chrome blocks must be copied verbatim so every readout looks like every
other. Before writing, read <skill-directory>/references/doc-guide.md and follow it.

Output:
- Write ONE self-contained HTML file to ~/.readouts/<YYYY-MM-DD>-<topic-slug>.html
  (create ~/.readouts if it doesn't exist; suffix -2, -3, ... if the name is taken;
  get the date from `date +%F`).
- Embed referenced source per the doc guide when a repo is checked out
  (<skill-directory>/scripts/embed_snippets.py).
- Refresh the readouts index: python3 <skill-directory>/scripts/update_index.py
  (fully regenerates ~/.readouts/index.html listing every readout).
- When the file is written, open it with `open <path>` (skip this if the environment is
  headless).
- Report back to your orchestrator: the absolute file path, a 2–3 sentence summary of what
  the document covers, and anything you could not verify.

フォールバック

• 子の起動が利用できない、または拒否された場合: references/doc-guide.md に従って、自分でドキュメントを作成してください。リサーチ用サブエージェントが利用できる場合は、会話のマイニングやコード調査をそれに委任することで、自分のコンテキストを引き続き軽量に保てます。
• 子が会話履歴を検索できない場合 (スナップショットモード。子はこれを報告してきます): 子が処理を続けられるよう、調査結果を要約したダンプを返信してください。プロンプトにペイロードを含めるのが正しい選択となる唯一のケースです。
• 会話の代わりにユーザー提供の素材がある場合 (文字起こし、ファイル、リンク): その素材をソースとして扱ってください。ワークフローのその他はすべて変更されません。