wayfinder

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

目的地は取り組みごとに異なり、それを名付けることが道筋を描く最初の行為です。目的地によって、すべてのチケットの内容が決まります。引き継いで反復するための仕様かもしれませんし、計画を始める前に確定すべき判断かもしれません。あるいは、データ構造の移行のように、その場で行う変更かもしれません。マップはドメインに依存しません。エンジニアリング作業でも、コースのコンテンツでも、形に合うものであれば何でも対象になります。

計画を立て、実行はしない

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

名前で参照する

すべてのマップとチケットはイシューであり、それぞれ名前、つまりタイトルがあります。人間が読むすべての文章（説明や、マップの「これまでの判断」）では、裸の ID、番号、スラッグではなく、名前で参照してください。#42, #43, #44 が並ぶと読み取れませんが、名前ならひと目でわかります。ID と URL がなくなるわけではありません。名前がリンクを包みますが、ID と URL は名前の 中に 含まれ、名前の代わりにはなりません。

マップ

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

マップは索引であり、保管場所ではありません。決定した内容を一覧にし、詳細が記載されたチケットを示します。判断はそれぞれ 1 か所、つまり対応するチケットに記載するため、マップでは判断を繰り返さず、要約してリンクするだけです。

マップ、その子チケット、ブロック関係、フロンティアのクエリが実際にどこに置かれるかは、トラッカーによって異なります。 イシュートラッカーは、あらかじめ指定されているはずです。指定されていない場合は、ユーザーに /setup-matt-pocock-skills を実行するよう伝えてください。このリポジトリでそれらをどう表現するかは、トラッカーのドキュメントの「Wayfinding operations」セクションを確認してください。トラッカーが指定されていない場合は、デフォルトでローカル Markdown トラッカーを使ってください。

マップの本文

セッションごとに 1 回読み込む、低解像度のマップ全体です。オープンチケットは一覧に含めません。オープンチケットは子イシューであり、クエリで見つけます。

## 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 をチケットとして昇格させます。昇格させた箇所はそれぞれまだ明確でない事項から削除し、新しいチケットにのみ記載します。回答によって、このチケットまたは別のチケットが目的地の先にあると判明した場合は、経路上で解決するのではなく、対象外と判断します。決定によってマップの他の部分が無効になった場合は、該当するチケットを更新または削除します。

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