showcase

納品物はナラティブです。各ポイントを、それを証明する媒体で順に示します。_どのように作られているか_はテキスト形式で、_どのように流れるか_は図で、_何が見えるか_はキャプチャで示します。すべてのビジュアルは証拠です。伝えるべきポイントが伝わる最小限のビューだけを示し、それ以外は含めません。対象はプロダクトとアーキテクチャとし、コードそのものが主題である場合に限り、コードの詳細に踏み込みます。

このスキルでは、ページに何を載せるかを決めます。/to-artifact が作成と公開を行い、ステップ 4 のブリーフが引き継ぎ内容になります。ユーザーが名前を挙げて指定した媒体は、以下のすべてのデフォルトより優先されます。

1. 主題を決める

主題が示されている最初の情報源から選びます。呼び出しで指定されたもの、今セッションで話し合っている主題、ユーザーがリンクした PR または issue のいずれかです。すべての情報源が空の場合は、質問します。

主題を 1 行で書いたら完了です。

2. ポイントの範囲を決める

ページで扱うポイントのリストと、それらを伝える順序を決めます。順序は主題に沿って組み立てます。よくあるパターンは次のとおりです。

機能のウォークスルー — その機能が何をするかから始め、必要であれば最後に、その仕組みへと掘り下げます。その機能が何をするものか、誰のためにどんな役割を果たすのかを示します。操作の流れを、各ステップにつき 1 つのキャプチャで順に説明します。実際の画面名と状態を示す 1 つの図で、処理の流れを説明します。ファイル参照でエントリーポイントの場所を示します。

アーキテクチャの概要 — 全体の構成を示し、各要素の名前とシステム全体での役割を説明します。主要な経路を、データフロー図またはシーケンス図で示します。各要素について、役割、入力、出力、エントリーポイントを説明します。システムが外部と接する境界と、それぞれの境界を通過するものを示します。

バグの仕組み — バグについては過去形、修正については現在形で説明します。画面上に現れるバグの場合は、再現手順のストーリーボードでユーザーに見えた症状を示します。仕組みでは、失敗した経路、実際の状態、挙動が分岐した箇所を説明します。修正は、コードへのリンクを含む文章で説明します。同じフローを修正後に示し、効果を証明します。

複数の順序が主題に当てはまる場合は、主題に基づく具体的な候補を挙げて、AskUserQuestion を使い、一度だけ質問します（multiSelect）。順序が明らかな場合は、質問を省略します。いずれの場合も、扱う内容について尋ねるのはこれが最後です。

ポイントを順番に並べたら完了です。

3. メディアを集める

図形 — 各ポイントを証明するものを選びます。分岐が重要で構文が重要でない場合は、ロジックを擬似コードで示します。実行時の制御フローには、何が何をどの順序で呼び出すかを示す呼び出しツリーを使います。UI 構造には、重要な状態とモジュール境界を含むコンポーネントツリーを使います。ファイルの責務や大規模なリファクタリングの概要には、各項目の目的を1行ずつ記したファイルツリーを使います。周囲の構造がすでにある場合に何が変わるかを示すには差分を使い、トピックに合わせて差分の形を選びます。UI の変更にはコンポーネントツリー、呼び出し順序の変更には呼び出しツリーを使います。コンポーネントの相互作用、データフロー、状態機械には、/artifact-diagramming に従って図を描きます。実際の状態、実際の名前、実際の分岐条件を使い、何が流れるかをラベルにした矢印を付けます。

キャプチャ — 対象が画面に表示される場合、キャプチャで一連の流れを伝えます。アプリが表示できたはずの画面の代わりに図を使うのは不備です。

/run を呼び出してアプリを起動し、その URL からフローを操作します。フローごとにサブエージェントを割り当てるのが望ましいです。フローを並行して実行でき、ログがコンテキストに入らないためです。各ステップにつきキャプチャを1つ、順番に取得し、それぞれについてユーザーが直前に行った操作と画面上で変化した点を記録します。キャプチャはディスク上のファイルとして保存され、補助ファイルとしてページに渡されるため、ピクセルデータもコンテキストに入りません。送信前にそれぞれをリサイズして圧縮します。各フローのエージェントはキャプチャをディスクに保存したらブラウザーセッションを終了します。すべてのフローが完了したら、/run がアプリを起動していた場合は停止します。

予定していたキャプチャを作成できない場合（アプリが起動しない、またはフローを操作できないなど）は、作業を中断して確認を求め、キャプチャなしのページも選択肢として提示します。

調査 — まず、このセッション自体のコンテキストを情報源とします。それ以外は、ポイントの内容に応じて範囲を決めます。仕組みが必要なポイントには /how、動機が必要なポイントには /why を呼び出します。通常、UI の一連の操作にはどちらも必要ありません。どちらも広範な調査を行うため（/how は観点ごとに探索エージェントを割り当て、/why は情報源ごとに調査エージェントを割り当てた後に統合エージェントを起動します）、必要なポイントに対して呼び出します。

すべてのポイントについて、それに適したメディアが揃ったら完了です。

4. ブリーフを作成して公開する

/to-artifact が作成する内容を確定する唯一のドキュメントとして、ブリーフをスクラッチパッドに書きます。

# Brief: <subject>

The subject, points, and media below are settled. Take them as given, and start at framing the reader's job.

## Subject

<one line>

## Points

1. <what this point proves> — capture — `shots/01-signin.png`
2. <what this point proves> — sequence diagram
3. <what this point proves> — prose with file references

## Media

Publish these as supporting files:

- `shots/01-signin.png` — <what it shows, and what the reader just did>

新しいエージェントを割り当て、ブリーフのパスを指定して /to-artifact を呼び出します。ブリーフがそのコンテキストのすべてです。

ユーザーがリンクを受け取ったら完了です。