wayfinder

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

目的地は取り組みごとに異なり、道筋を描き始める最初の作業は、その目的地に名前を付けることです。目的地はすべてのチケットの方向性を決めます。引き継いで反復を重ねる仕様書、計画を始める前に確定すべき判断、データ構造の移行のようにその場で行う変更などが考えられます。マップは特定の分野に限定されず、エンジニアリング作業でも、教材コンテンツでも、この形式に合うものなら何でも扱えます。

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

Wayfinder はデフォルトで計画を立てます。各チケットでは判断をひとつ解決し、進むべき道が明らかになり、誰かが作業に取りかかる前に決めておくことがなくなった時点で、マップは完成です。実作業に着手したくなるのは、たいていマップの端まで来ており、引き継ぎのタイミングであることを示しています。取り組みのNotesでこれを上書きすれば、マップ自体に実行作業を含めることもできますが、そうでなければ、成果物ではなく判断を作成してください。

名前で参照する

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

マップ

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

マップはインデックスであり、情報を保管する場所ではありません。マップには決定事項を列挙し、その詳細を記載したチケットへのリンクを載せます。決定事項は、それぞれ該当するチケットのひとつの場所にのみ記載します。そのため、マップでは決定を繰り返さず、概要を記してリンクするだけです。

マップ、子チケット、ブロック関係、フロンティアの検索が実際にどこに保存されるかは、トラッカーによって異なります。 イシュートラッカーはすでに指定されているはずです。指定されていない場合は、ユーザーに/setup-agent-skillsを実行するよう伝えてください。このリポジトリでそれらをどう扱うかは、トラッカーのドキュメントの「Wayfinding operations」セクションを参照してください。トラッカーが指定されていない場合は、デフォルトでローカル 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 がチケットを識別します。本文には、ひとつのエージェントセッション（トークン上限 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 をチケットとして昇格させます。昇格させた箇所はそれぞれまだ明確でない事項から削除し、新しいチケットにのみ記載します。回答によって、このチケットまたは別のチケットが目的地の先にあると判明した場合は、経路上で解決するのではなく、対象外と判断します。決定によってマップの他の部分が無効になった場合は、該当するチケットを更新または削除します。

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