wayfinder

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

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

実行ではなく計画を立てる

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

名前で参照する

すべてのマップとチケットはイシューであり、名前、つまりタイトルがあります。人間が読むあらゆる箇所（説明、マップの「これまでの判断」など）では、番号や 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 がその識別子です。本文は、エージェントの 100K トークンセッション 1 回分に収まる質問です。

## Question

<the decision or investigation this ticket resolves>

各チケットには wayfinder:<type> ラベルが付きます。種類は research、prototype、grilling、task のいずれかです（チケットの種類を参照）。マップとそのチケットに付けるラベルは wayfinder: ラベルのみです。ready-for-agent のようなトリアージラベルは付けません。これらは実装作業ではなく、意思決定を表すものです。

もう 1 つのラベルは in-progress です。セッションがチケットを引き受けている間に付けます（下記のループを参照）。これは引き受け済みであることを示すもので、トリアージラベルではありません。

セッションは、作業を始める前に、マップを進める開発者を担当者に設定して、チケットを引き受けます。こうすることで、並行している他のセッションはそのチケットをスキップします。この担当者設定がそのまま引き受け済みであることを示します。未割り当てのオープンチケットは、未引き受けです。

ブロックには、トラッカーのネイティブな依存関係を使います。トラッカー自身の UI でフロンティアが_視覚的に_表示されるため、人間はマップを開かなくても、どのチケットに着手できるかを確認できます。ネイティブなブロック機能がないトラッカーに限り、本文の規約で代用します。チケットをブロックしているすべてのチケットがクローズされると、そのチケットはブロック解除済みです。フロンティアとは、オープンで、ブロック解除済みかつ未引き受けの子チケット、つまり既知の領域の最前線です。

• 関連：マップやチケットが、ブロックはされないものの、別のチケットの結果に意図的に依存する場合は、本文に「Related: #n (why)」と記載します。理由は、背景を把握しているセッションが一度だけ記述し、後から推測して補うことはありません。

回答は本文には含めず、解決時に記録します（マップに沿って進めるを参照）。チケットの解決中に作成したアセットは、課題にリンクし、本文に貼り付けないでください。

チケットの種類

すべてのチケットは、本人の言葉を話す人間と_一緒に_取り組む HITL（human in the loop）か、エージェントだけで進める AFK のいずれかです。HITL チケットは、その場でのやり取りを通じてのみ解決できます。エージェントが人間の役割を代行することはありません（グリリングエージェントが自分の質問に答えるのは、この原則に反します）。

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

戦場の霧

マップは 意図的に 不完全なままにします。まだ見えていないものを図示しないでください。進行中のチケットの先には、戦場の霧があります。今後必要になるとわかっているものの、未解決の問いに左右されるため、まだ具体化できない決定や調査の見通しがぼんやりと見えています。チケットを解決すると、その先の霧が晴れ、具体化できるようになった内容が新しいチケットとして一つずつ追加されます。目的地までの道筋が明らかになり、チケットがなくなるまで続きます。

マップの Not yet specified セクションには、そのぼんやりとした見通しを書き留めます。つまり、疑問に思われる問いや、後で再検討する領域です。目的地 へ向かう 未開拓の領域であり、ここにあるものはすべて対象範囲内ですが、チケットにできるほど明確ではありません。見通しに応じて、大まかにでも詳しくでも書いてください。取り組みがどこへ向かっているのかを読む共同作業者のための道しるべにもなります。

霧か、チケットか？ 判断基準は、今その問いに答えられるかどうか ではなく、問いを正確に述べられるかどうかです。

• 問いがすでに明確なら、たとえ阻害要因があってまだ着手できなくても、チケットにします。
• まだそこまで明確に表現できないなら、Not yet specified にします。霧をあらかじめチケット単位に細分化しないでください。霧はチケットよりも大まかなものであり、未開拓の領域に達したとき、一つの領域から複数のチケットが生まれることも、チケットが生まれないこともあります。

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

対象範囲外

霧は常に目的地 へ向かって 広がります。目的地によって対象範囲が定まるため、その先の作業は対象範囲外です。霧ではなく、Not yet specified に含めるものでもありません。マップ上に独立した Out of scope セクションを設け、この取り組みの対象外と意識的に判断した作業を記載します。ここに分類する基準は、明確さではなく対象範囲です。

対象範囲外の作業が後から対象範囲内になることはありません（未開拓の領域は目的地で終わるため）。再び対象となるのは、目的地を引き直した場合のみです。その場合も、再開ではなく新たな取り組みとして扱います。

対象範囲外と判断するのは、作業範囲を定める行為であり、道筋の一歩ではありません。すでに存在するチケットが目的地の先にあると判明した場合（図示する際に誤って対象範囲に含めていた場合、または解決によって判明した場合）は、クローズし（クローズ済みのチケットは未開拓の領域の外にあることが明確になります）、要点と対象範囲外である理由を Out of scope セクションに一行で記載し、クローズしたチケットにリンクします。実際にたどった道筋を記録する Decisions so far には含めません。対象範囲の境界は、その道筋の一歩ではないためです。

呼び出し方法

モードは2種類あります。どちらの場合も、調査チケットを除き、1回のセッションで複数のチケットを解決してはいけません。

地図を作成する

ユーザーは、漠然としたアイデアを提示して実行を依頼します。

1. 目的地を決める。 Skill ツールを「grilling」と「domain-modeling」でそれぞれ呼び出し、この地図が何にたどり着くためのものなのか、つまり仕様、決定事項、変更内容を明確にします。目的地によって範囲が決まるため、最初に確定します。
2. フロンティアをマッピングする。 今度は幅優先で再び掘り下げます。どれか一つの論点だけを深掘りするのではなく、全体にわたって検討し、未決事項と今すぐ着手できる最初のステップを明らかにします。これによって曖昧さが何も見つからない場合（目的地までの道筋がすでに明確で、全行程が1回のセッションで完了できる場合）、地図は不要です。そこで止め、次にどう進めたいかユーザーに尋ねます。
3. 地図を作成する（ラベルは wayfinder:map）：Destination と Notes を記入し、Decisions-so-far は空欄にして、曖昧な点を Not yet specified にまとめます。
4. 今すぐ仕様を決められるチケットを作成する：地図の子課題として作成した後、2回目のパスでブロッキング関係を設定します（チケット同士を参照するには、先に ID が必要です）。このパスで相互参照も記載し、実際の ID を使います。プレースホルダーの #<n> は無関係な課題に自動リンクされます。ブロッキング関係を設定すると、チケットはフロンティアとブロック中の項目に振り分けられます。まだ仕様を決められない項目はすべて曖昧なままにし、Not yet specified セクションに残します。
5. リサーチのサブエージェントを起動する。 作成した research チケットごとにサブエージェントを起動し、Skill ツールを「research」で呼び出して並行して解決します。チケットからコンテキストポインターを付け、調査結果を使い捨ての research/<name> ブランチに記録します。ブランチをプッシュしますが、PR は作成しません。マージされることはありません。
6. 停止します。地図の作成は1回のセッションで行い、決定事項の解決は一切行いません。

地図に沿って進める

ユーザーは地図を指定して実行を依頼します（URL または番号）。チケットは任意です。ユーザーがチケットを指定しない場合は、次の決定事項をこちらで選びます。

1. 地図を読み込みます。すべてのチケット本文ではなく、概要を確認します。
2. チケットを選びます。ユーザーが指定した場合はそれを使います。そうでなければ、フロンティアの先頭にあるチケットを順に選びます。担当を引き受け、作業を始める前に自分を割り当て、in-progress ラベルを追加します。
3. wayfinder:<type> ラベルが示すタイプとして解決します（チケットタイプを参照）。本文だけでなくラベルを確認します。タイプは本文には記載されていません。必要に応じて詳細を確認します。関連するチケットやクローズ済みチケットの全文は必要に応じて取得し、## Notes ブロックに記載されたスキルについて Skill ツールを呼び出します。判断に迷った場合は、Skill ツールを「grilling」と「domain-modeling」でそれぞれ呼び出します。
4. 解決内容を記録します。回答を解決コメントとして投稿し、課題をクローズして in-progress ラベルを削除し、地図の Decisions-so-far にコンテキストポインターを追加します。
5. 新たに判明したチケットを追加します（作成してから接続）。回答によって仕様を決められるようになった曖昧な項目は、Not yet specified から該当する記述を削除してチケットに昇格させます。回答から、チケット（現在のものでも別のものでも）が目的地の範囲外にあると判明した場合は、経路上で解決するのではなく、対象外と判断します。決定によって地図の他の項目が無効になる場合は、該当するチケットを更新または削除します。

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