wayfinder

大まかなアイデアが生まれました。1回のエージェントセッションでは大きすぎ、霧に包まれています。ここから目的地までの道筋は、まだ見えていません。Wayfinding とは、目的地に向かって突き進むことではなく、その道筋を見つけることです。このスキルでは、リポジトリのイシュートラッカー上に共有マップとして道筋を描き、意思決定チケット（解決によって決定を下すための質問であり、実行する作業の一部ではありません）に1つずつ取り組み、ルートが明確になるまで進めます。

目的地は取り組みごとに異なり、その名前を決めることが、道筋を描く最初の作業です。名前によって、すべてのチケットの内容が形作られます。引き継いで反復する仕様書の場合もあれば、計画を始める前に確定する決定の場合もあり、データ構造の移行のように、その場で行う変更の場合もあります。マップは特定の分野に限定されません。エンジニアリング作業、コースのコンテンツなど、どんなものでもこの形式に合えば対象になります。

計画する。実行はしない

Wayfinder はデフォルトで計画を行います。各チケットで決定を下し、道筋が明確になって、誰かが実行に移る前に決めておくべきことがなくなった時点でマップは完成です。作業をそのまま実行したくなるのは、たいていマップの端までたどり着き、引き継ぐ時期が来たという合図です。取り組みのNotesでこの方針を上書きし、実行もマップに含めることはできますが、特に指定がなければ、成果物ではなく決定を生み出してください。

名前で参照する

すべてのマップとチケットはイシューであり、名前、つまりタイトルがあります。人が読むすべてのもの（ナレーションや、マップの「これまでの決定」）では、ID、番号、スラッグだけを使わず、名前で参照してください。#42, #43, #44が並んでいても読めませんが、名前なら一目でわかります。IDとURLもなくなるわけではありません。名前にリンクを付けますが、IDとURLは名前の中に含め、名前の代わりとして使わないでください。

マップ

マップは、このリポジトリのイシュートラッカー上にあるwayfinder:mapラベル付きの単一のイシューで、正式な成果物です。そのチケットはマップの子イシューです。

マップは索引であり、情報の保管場所ではありません。決定事項を列挙し、詳細を記したチケットを示します。決定事項は必ず1か所、つまりそのチケットに記載し、マップでは言い換えず、要約してリンクするだけにします。

マップ、子チケット、ブロック関係、フロンティアのクエリを実際にどこに置くかは、トラッカーによって異なります。 外部のイシュートラッカーを使うのは、ユーザーまたはチャット履歴でイシューリポジトリが指定されている場合に限ります。それ以外の場合は、デフォルトでローカル Markdown トラッカーを使用します。

マップ本文

セッションごとに一度読み込む、マップ全体の概要です。オープンなチケットは列挙しません。オープンなチケットは子イシューであり、クエリで取得します。

## Destination

<what reaching the end of this map looks like: the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Decisions so far



- [<closed ticket title>](link): <one-line gist of the answer>

## Not yet specified



## Out of scope

チケット

各チケットはマップの子イシューであり、トラッカーのイシュー ID がその識別子です。本文は、1回の100Kトークンのエージェントセッションで扱える規模の質問です。

## Question

<the decision or investigation this ticket resolves>

各チケットにはwayfinder:<type>ラベルを付けます。種類はresearch、prototype、grilling、taskのいずれかです（チケットの種類を参照）。

セッションでは、作業を始める前に、まずマップを進める開発担当者をチケットに割り当てて、そのチケットを「確保」します。こうすることで、並行しているセッションはそのチケットをスキップできます。担当者への割り当てがそのまま確保を意味します。オープンで担当者が割り当てられていないチケットは、未確保です。

ブロックには、トラッカーのネイティブな依存関係を使います。これは、トラッカー独自の UI でフロンティアを_視覚的に_表示し、人がマップを開かなくても、どのチケットに取り組めるかを確認できるため、不可欠です。ネイティブなブロック機能がないトラッカーに限り、本文での記載方法に切り替えます。ブロックしているすべてのチケットがクローズされると、そのチケットはブロックされていない状態になります。フロンティアとは、オープンで、ブロックされておらず、未確保の子チケット、つまり既知の範囲の端です。

回答は本文の一部ではありません。解決時に記録します（マップに取り組むを参照）。チケットの解決中に作成したアセットは、イシューからリンクし、貼り付けないでください。

チケットの種類

チケットはすべて、HITL（人間がループに参加し、自分自身の言葉で話す人間と_ともに_進める）か、エージェントだけで進める AFK のいずれかです。HITL チケットは、その場でのやり取りを通じてのみ解決します。エージェントが人間の側を代弁することはありません（質問を投げかけたエージェントが自分で回答するのは、ルール違反です）。

• Research（AFK）：ドキュメント、サードパーティの API、ナレッジベースなどのローカルリソースを読み、意思決定に必要な事実を明らかにします。「research」を指定して Skill ツールを呼び出すサブエージェントが解決します。現在の作業ディレクトリ外の知識が必要な場合に使用します。
• Prototype（HITL）：Skill ツールを「prototype」と指定して呼び出し、議論の精度を高めるための、低コストで大まかかつ具体的な成果物（概要、ラフ案、スタブ、UI／ロジックのコードなど）を作成し、反応を得ます。プロトタイプをアセットとしてリンクします。「どのような見た目にするか」「どのように動作させるか」が重要な問いの場合に使用します。
• Grilling（HITL）：対話です。デフォルトのケースです。Skill ツールを「grilling」と「domain-modeling」のそれぞれに対して、必ず 2 回呼び出します。
• Task（HITL または AFK）：_意思決定_の前に必要な手作業です。決めること、プロトタイプを作ること、調査することのいずれでもありませんが、完了するまで議論が進みません。サービスに登録して API を評価できるようにする、アクセス権を準備する、データを移動してその形を確認できるようにするといった作業です。何かを決定するのではなく、実際に作業を行う唯一の種類です。最終的な成果を提供するのではなく、意思決定を妨げているものを取り除くことで、チケットとしての価値を果たします。可能な場合はエージェントだけで進め（AFK）、そうでなければ人間に正確なチェックリストを渡します（HITL）。作業が完了した時点で解決となり、回答には実施内容と、その後のチケットで必要となる事実（認証情報の場所、新しい URL、行数など）を記録します。

不確定な領域

マップは_意図的に_不完全な状態です。まだ見えていないものを描き込まないでください。進行中のチケットの先には、不確定な領域があります。今後必要になるとわかっていても、まだ特定できない意思決定や調査が、ぼんやりと見える領域です。これらは未解決の問いに左右されます。チケットを解決すると、その先の不確定さが晴れ、仕様を定められるようになったものが新たなチケットとして一つずつ追加されます。目的地への道筋が明らかになり、チケットがなくなるまで続きます。

マップの Not yet specified セクションには、そのぼんやりとした見通しを記録します。後で再検討する必要があると思われる問いや領域を書きます。ここは目的地_へ向かう_未開拓の領域です。ここにあるものはすべて対象範囲内ですが、まだチケットにできるほど明確ではありません。見えている範囲で、簡潔に書いても詳しく書いても構いません。また、取り組みの方向性を確認する共同作業者への道しるべにもなります。

不確定な領域か、チケットか？ 判断基準は、今すぐ答えられるかどうか_ではなく_、今すぐ問いを正確に述べられるかどうかです。

• 問いがすでに明確なら、たとえブロックされていて、まだ着手できなくても、チケットにします。
• まだそれほど明確に表現できない場合は、Not yet specified にします。不確定な領域を、あらかじめチケット単位に細分化しないでください。ここはチケットより大まかな領域です。最前線がそこに達したときに、一つの領域から複数のチケットが生まれることも、チケットが一つも生まれないこともあります。

Not yet specified には、すでに決定したこと（これまでの決定）、進行中のチケット、対象範囲外のこと（次のセクション）は含めません。

対象外

Fog は常に目的地に向かってのみ集約されます。目的地によってスコープが決まるため、その先の作業は対象外です。fog ではなく、まだ明確でない事項にも含まれません。マップには専用の対象外セクションを設け、その取り組みでは意識的に除外した作業を記録します。ここに分類されるのは、明確さではなくスコープによるものです。

対象外の作業がフロンティアを越えて進むことはありません（フロンティアは目的地で止まります）。そのため、再び対象になるのは目的地を描き直した場合のみで、その際も再開ではなく、新しい取り組みとして扱います。

何かを対象外と判断するのはスコープ設定の行為であり、経路上のステップではありません。すでに存在するチケットが目的地の先にあると判明した場合（マップの作成時に誤ってスコープ内に含めた場合、または解決によって判明した場合）は、クローズし（クローズ済みチケットはフロンティア外であることが明確です）、対象外セクションに、要点と対象外である理由を一行で記載し、クローズしたチケットへのリンクを付けます。実際にたどった経路を記録するこれまでの決定事項には含めません。スコープの境界は経路上のステップではないためです。

呼び出し

モードは 2 つあります。どちらの場合も、調査チケットを除き、1 セッションで解決するチケットは 1 件までです。

マップを作成する

ユーザーが大まかなアイデアを提示して呼び出します。

1. 目的地を定めます。 Skill ツールを「grilling」と「domain-modeling」に対して 2 回呼び出し、このマップが何を目指すのか、つまり仕様、決定、または変更を明確にします。目的地によってスコープが決まるため、最初に確定させます。
2. フロンティアをマップします。 今度は幅優先で再度聞き取りを行います。特定のスレッドを深掘りするのではなく、全体にわたって展開し、未決定事項と、今すぐ着手できる最初のステップを明らかにします。ここで fog が見つからない場合（目的地までの道筋がすでに明確で、旅程全体が 1 セッションで終わるほど小さい場合）、マップは不要です。そこで止め、どのように進めたいかをユーザーに尋ねます。
3. マップを作成します（ラベル wayfinder:map）。目的地とメモを記入し、これまでの決定事項は空欄のままにして、fog をまだ明確でない事項に書き出します。
4. 今すぐ仕様を定められるチケットを作成します。マップの子イシューとして作成し、その後、2 回目の処理でブロック関係のエッジを設定します（相互参照するには、先にイシュー ID が必要です）。エッジを設定すると、チケットがフロンティア上かブロック中かに分類されます。まだ仕様を定められないものはすべて、まだ明確でない事項セクションの fog に残します。
5. 調査サブエージェントを起動します。 作成した各 research チケットについて、サブエージェントを起動し、Skill ツールを「research」で呼び出して並行して解決します。チケットからのコンテキストポインターを含め、調査結果を使い捨ての research/<name> ブランチに記録します。
6. 停止します。マップの作成は 1 セッションで行い、チケットを直接解決することはありません。

マップに沿って作業する

ユーザーがマップ（URL または番号）を指定して呼び出します。チケットの指定は任意です。指定がない場合は、ユーザーではなくあなたが次の決定事項を選びます。

1. マップを読み込みます。すべてのチケットの本文ではなく、低解像度のビューを確認します。
2. チケットを選びます。ユーザーが指定した場合は、そのチケットを使います。指定がなければ、フロンティア上の先頭のチケットを順番に選びます。担当に設定します。作業を始める前に、自分を担当者に割り当てます。
3. 解決します。必要に応じて詳細を確認します。関連チケットまたはクローズ済みチケットの全文を必要に応じて取得し、## Notes ブロックに記載されたスキルごとに Skill ツールを呼び出します。判断に迷う場合は、Skill ツールを「grilling」と「domain-modeling」に対して 2 回呼び出します。
4. 解決内容を記録します。回答を解決コメントとして投稿し、イシューをクローズして、マップの「これまでの決定事項」にコンテキストポインターを追記します。
5. 新たに判明したチケットを追加し（作成してからエッジを設定）、回答によって仕様を定められるようになった fog をチケットとして昇格させます。昇格させた箇所はそれぞれまだ明確でない事項から削除し、新しいチケットにのみ記載します。回答によって、このチケットまたは別のチケットが目的地の先にあると判明した場合は、経路上で解決するのではなく、対象外と判断します。決定によってマップの他の部分が無効になった場合は、該当するチケットを更新または削除します。

ユーザーはブロックされていないチケットを並行して進める場合があるため、他のセッションも同時にトラッカーを編集していることを想定してください。