wayfinder

漠然としたアイデアが届きました。1 回のエージェントセッションには大きすぎ、霧に包まれています。ここから目的地への道筋はまだ見えていません。ウェイファインディングとは、その道筋を見つけることであり、目的地に向かって突進することではありません。このスキルは、リポジトリのイシュートラッカー上に共有マップとして道筋を描き、そしてその意思決定チケット（実行すべきビルドの断片ではなく、解決することが意思決定である問い）を、道筋が明確になるまで 1 つずつ処理していきます。

目的地は取り組みごとに異なり、それを名付けることがチャート作成の最初の行為です。それがあらゆるチケットを形作ります。引き継いで反復していく仕様書かもしれないし、計画を始める前に固めるべき意思決定かもしれないし、データ構造のマイグレーションのようにその場で行う変更かもしれません。マップはドメイン非依存です。エンジニアリングの仕事、コースのコンテンツ、形に当てはまるものなら何でも構いません。

計画せよ、実行するな

Wayfinder はデフォルトで計画です。各チケットは意思決定を解決し、マップは道筋が明確になった時点で完了します。誰かが実際に作業をしに行く前に、決めるべきことは何も残っていません。ただ作業をやってしまいたいという衝動は、通常、マップの端に到達し、引き継ぎの時が来たというシグナルです。取り組みはそのNotesでこれを上書きし、実行をマップ自体に持ち込むこともできますが、それがなければ、成果物ではなく意思決定を生み出してください。

名前で参照する

すべてのマップとチケットはイシューであるため、名前、すなわちタイトルを持ちます。人間が読むものすべて（ナレーション、マップの Decisions-so-far）では、その名前で参照してください。裸の id、番号、スラッグで参照してはいけません。#42, #43, #44 の壁は読めませんが、名前は一目で読めます。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 のいずれかです（チケットの種類を参照）。wayfinder: ラベルはマップとそのチケットが持つ唯一のラベルであり、ready-for-agent のようなトリアージラベルを決して持ちません。それらは実装作業ではなく意思決定だからです。

セッションはチケットを、作業を始める前にまず、マップを進める開発者に割り当てることでクレームします。そうすることで、同時並行のセッションがそれをスキップします。その担当者こそがクレームです。オープンで未割り当てのチケットは未クレームです。

ブロッキングはトラッカーのネイティブな依存関係を使用します。これは不可欠です。なぜなら、トラッカー自身の 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. フロンティアをマッピングします。 今度は幅優先でもう一度問いを掘り下げます。1つのスレッドを深く掘り下げるのではなく、全体に広げて、未決定事項と今すぐ着手できる最初のステップを明らかにします。ここで Fog が見つからない場合（目的地までの道筋がすでに明確で、全行程が1セッションで完了するほど小さい場合）は、マップを作成する必要はありません。そこで止めて、どのように進めたいかをユーザーに尋ねます。
3. マップを作成します（ラベルは wayfinder:map）。Destination と Notes に入力し、Decisions-so-far は空のままにして、Fog を未指定に書き出します。
4. 今すぐ仕様を定められるチケットを子課題として作成し、その後、第2パスでブロック関係を設定します（課題同士を相互参照するには、先に ID が必要です）。このパスで、実際の ID を使って相互参照も記述します。プレースホルダーの #<n> は無関係な課題へのリンクが自動作成されます。ブロック関係を設定すると、チケットはフロンティアとブロック中のチケットに振り分けられます。まだ仕様を定められないものはすべて Fog、つまり未指定セクションに残します。
5. リサーチのサブエージェントを起動します。 作成した各 research チケットについて、Skill ツールを「research」で呼び出すサブエージェントを起動し、並行して解決させます。チケットのコンテキストポインターを使い、調査結果を使い捨ての research/<name> ブランチに記録します。ブランチはプッシュしますが、PR は作成しません。マージされることはありません。
6. 停止します。マップ作成は1セッションで行う作業です。チケットを自分で解決することはありません。

マップを進める

ユーザーはマップ（URL または番号）を指定して呼び出します。チケットは任意です。指定がなければ、ユーザーではなく、次の判断事項を選びます。

1. マップを読み込みます。すべてのチケット本文ではなく、低解像度のビューを読み込みます。
2. チケットを選びます。ユーザーが指定した場合は、それを使います。指定がなければ、順番に最初のフロンティアチケットを選びます。担当を割り当てます。作業を始める前に、自分に割り当てます。
3. wayfinder:<type> ラベルが示す種類として解決します（チケットの種類を参照）。本文だけでなく、ラベルを確認してください。本文には種類が記載されていません。必要に応じてズームします。関連チケットまたはクローズ済みチケットの全文を必要に応じて取得し、## Notes ブロックに記載されたスキルの Skill ツールを呼び出します。判断に迷ったら、「grilling」と「domain-modeling」の両方について、Skill ツールを呼び出します。
4. 解決内容を記録します。回答を解決コメントとして投稿し、Issue をクローズして、マップの「これまでの決定」にコンテキストへのポインターを追記します。
5. 新たに明らかになったチケットを追加し（作成してから関連付けます）、回答によって仕様を定められるようになった曖昧な項目を確定します。確定した各項目は未指定から削除し、新しいチケットのみに記載されるようにします。回答によって、チケット（今回のもの、または別のチケット）が目的地の範囲外にあると判明した場合は、ルート上で解決するのではなく、対象外とします。決定によってマップの他の部分が無効になる場合は、それらのチケットを更新または削除します。

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