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（human in the loop。自分自身の言葉で話す人間と_ともに_進める）か、エージェント単独で進めるAFKのいずれかです。HITL チケットは、その場でのやり取りを通じてのみ解決します。エージェントが人間の側に立って発言することはありません（自分の質問に自分で答える尋問役のエージェントは、この原則に反しています）。

• リサーチ（AFK）：ドキュメント、サードパーティ API、ナレッジベースなどのローカルリソースを読み、意思決定の前提となる事実を明らかにします。「research」スキルを読み込んだサブエージェントが解決します（SKILL.md を読みます）。現在の作業ディレクトリ外の知識が必要な場合に使用します。
• プロトタイプ（HITL）：議論の精度を高めるため、反応を得られる安価で粗削りな具体物（概要、ラフ案、スタブ、UI／ロジックのコードなど）を「prototype」スキルを読み込んで作成します（SKILL.md を読みます）。プロトタイプをアセットとしてリンクします。「どのように見えるべきか」「どのように動作すべきか」が重要な問いである場合に使用します。
• グリリング（HITL）：対話です。標準的なケースです。「grilling」と「domain-modeling」の2つのスキルを必ず読み込みます（それぞれの SKILL.md を読み、指示に従います）。
• タスク（HITL または AFK）：_意思決定_を行う前に実施しなければならない手作業です。判断、プロトタイプ作成、リサーチのいずれも必要ありませんが、完了するまでは議論が進められません。サービスに登録してその API を評価できるようにする、アクセス権を用意する、データを移動してその形式を確認できるようにする、といった作業です。これは、意思決定ではなく実行を担う唯一の種類です。目的地を届けるのではなく、意思決定を進められるようにすることで、存在意義があります。可能な場合はエージェント単独で進めます（AFK）。そうでない場合は、人間に明確なチェックリストを渡します（HITL）。作業が完了した時点で解決となり、回答には実施内容と、その結果わかった事実（認証情報の保存場所、新しい URL、行数など）を記録します。後続のチケットは、それらの情報に依存します。

霧の中

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

そのぼんやりとした見通しを書き留める場所が、マップの未指定セクションです。後で再検討する疑問や領域を記します。これは目的地に_向かう_未知の領域です。ここにあるものはすべて対象範囲内ですが、チケットにできるほど明確ではありません。見通せる範囲で、自由に、あるいは詳細に記述してください。作業がどこへ向かっているかを把握する共同作業者への道しるべにもなります。

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

• 問いがすでに明確なら、作業が妨げられていて、まだ着手できなくてもチケットにします。
• まだそれほど明確に表現できないなら、未指定のままにします。霧をあらかじめチケット単位に切り分けてはいけません。霧はチケットよりも粗いものであり、境界にたどり着いたとき、一つの箇所から複数のチケット、またはチケットが一つも生まれないことがあります。

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

スコープ外

Fog は常に、目的地に向かってのみ進みます。目的地によってスコープが定まるため、その先の作業はスコープ外です。Fog ではなく、未指定にも属しません。マップ上に独立したスコープ外セクションを設け、_この_取り組みで意識的に対象外とした作業を記します。ここに分類するのは、明確さではなくスコープです。

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

何かをスコープ外とするのはスコープを定める行為であり、道筋上のステップではありません。すでにあるチケットが目的地の先にあると判明した場合（マップ作成中に誤ってスコープ内に含めた場合、または解決過程で判明した場合）は、クローズしてください（クローズ済みチケットはフロンティアの外であることが明確です）。そして、クローズしたチケットへのリンクを添えて、要点とスコープ外である理由をスコープ外セクションに一行で記します。実際にたどった道筋を記録するこれまでの決定事項には含めません。スコープの境界は、その道筋上のステップではありません。

呼び出し

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

マップを作成する

ユーザーが漠然としたアイデアを提示して呼び出します。

1. 目的地を定めます。 「grilling」と「domain-modeling」のスキルを読み込み（それぞれの SKILL.md を読み、その手順に従います）、このマップが何を目指すのか、つまり仕様、決定、変更を明確にします。目的地によってスコープが定まるため、最初に確定させます。
2. フロンティアをマップします。 今度は幅優先で再度掘り下げます。個々のスレッドを深掘りするのではなく、領域全体に視野を広げ、未決定事項と、今すぐ着手できる最初のステップを洗い出します。ここで Fog が見つからなかった場合（目的地までの道筋がすでに明確で、旅全体が 1 回のセッションで済むほど小さい場合）、マップは不要です。そこで止めて、どのように進めたいかユーザーに尋ねます。
3. マップを作成します（ラベルは wayfinder:map）。Destination と Notes を記入し、Decisions-so-far は空のままにして、Fog を未指定に書き出します。
4. 今すぐ詳細を指定できるチケットを作成します。マップの子イシューとして作成し、その後、2 回目のパスでブロッキングの関係を設定します（イシュー同士を参照するには、先に ID が必要です）。このパスで、実際の ID を使って相互参照も記入します。プレースホルダーの #<n> は、無関係なイシューに自動リンクされます。関係を設定すると、チケットはフロンティアとブロック済みに整理されます。まだ詳細を指定できない内容はすべて Fog、つまり未指定セクションに残します。
5. 調査サブエージェントを起動します。 作成した research チケットごとにサブエージェントを起動し、「research」スキルを読み込ませます（SKILL.md を読みます）。チケットからのコンテキストポインターを使い、調査結果を一時的な research/<name> ブランチに記録して、並行して解決します。ブランチはプッシュしますが、PR は作成しません。マージされることはありません。調査結果のパスを含むプッシュが完了の通知です。プッシュされたらファイルを読みます。ただし、調査はセッション単位であり、マップ作成はここで止まるため、今回のセッションが終わるまでに実行が完了しなかった場合は、後のセッションでブランチにチェックポイントされた調査結果から再開します。
6. 止めます。マップ作成は 1 回のセッションで行う作業であり、チケットを自分で解決することはありません。

マップに沿って作業する

ユーザーはマップ（URL または番号）を指定して実行します。チケットの指定は任意です。指定がない場合、次に判断するのはユーザーではなく、あなたです。

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

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