wayfinder

1 つのエージェントセッションでは大きすぎ、まだ全体像が見えないアイデアが舞い込みました。ここから 目的地 までの道筋は、まだ見えていません。Wayfinding では、目的地に向かって突き進むのではなく、そこへ至る道を見つけます。このスキルでは、リポジトリのイシュートラッカー上に 共有マップ として道筋を描き、意思決定チケット（解決するのが実装作業の一部ではなく意思決定である質問）を 1 件ずつ処理して、道筋が明確になるまで進めます。

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

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

Wayfinder はデフォルトで 計画 を行います。各チケットで意思決定を解決し、誰かが実行に移る前に決めることがなくなり、道筋が明確になった時点でマップは完成です。作業をそのまま実行したくなるのは、たいていマップの端まで到達し、引き継ぎの時期が来たことを示すサインです。取り組みの Notes でこれを上書きし、マップ内で実行まで進めることもできますが、そうした指定がない場合は、成果物ではなく意思決定を生み出してください。

名前で参照する

マップもチケットもすべてイシューであり、それぞれに 名前、つまりタイトルがあります。人間が読むすべての内容（説明、マップの「決定事項」）では、単独の ID、番号、スラッグではなく、名前で参照してください。#42、#43、#44 と並べられても意味がわかりませんが、名前なら一目で読めます。ID と URL がなくなるわけではありません。名前がリンクを包みますが、ID と URL は名前の 内側 に含め、名前の代わりに使わないでください。

マップ

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

マップは 索引 であり、情報の保管場所ではありません。決定事項を列挙し、その詳細を記載したチケットを示します。決定事項が記載される場所は、対応するチケットの 1 か所だけです。そのため、マップでは決定事項を繰り返さず、概要を記してリンクするだけにします。

マップ、その子チケット、ブロック関係、フロンティアのクエリを実際にどこで管理するかは、トラッカーによって異なります。 イシュートラッカーは事前に指定されているはずです。指定されていない場合は /setup-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>

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

セッションでは、作業を始める 前に チケットを最初に割り当てて、マップを進める開発者がそのチケットを 確保 します。これにより、並行しているセッションはそのチケットをスキップできます。割り当て先が確保を示します。未完了で、誰にも割り当てられていないチケットは未確保です。

ブロックには、トラッカーの 標準の 依存関係を使います。これは、トラッカー独自の UI でフロンティアが 視覚的に 表示され、人間がマップを開かなくても着手できるものを確認できるため、不可欠です。標準のブロック機能がないトラッカーに限り、本文内の規約を代わりに使います。チケットをブロックしているすべてのチケットがクローズされると、そのチケットは ブロック解除済み になります。フロンティア は、未完了かつブロック解除済みで、未確保の子イシュー、つまり既知の範囲の端です。

回答は本文には含めません。解決時に記録します（マップの作業を進めるを参照）。チケットの解決時に作成した成果物は、イシューに貼り付けるのではなく、イシューからリンクします。

チケットの種類

すべてのチケットは、本人の代わりに人間が回答するのではなく、本人が人間と一緒に取り組む HITL（human in the loop）か、エージェントだけで進める AFK のいずれかです。HITL チケットは、その場でのやり取りを通じてのみ解決します。エージェントが人間側に代わって回答することはありません（質問を投げかけたエージェントが自分で答えてしまうのは、これに反します）。

• Research（AFK）：ドキュメント、サードパーティ API、ナレッジベースなどのローカルリソースを調べ、意思決定に必要な事実を明らかにします。「research」を指定して Skill ツールを呼び出す サブエージェント が解決します。現在の作業ディレクトリ外の知識が必要な場合に使用します。
• Prototype（HITL）：アウトライン、ラフ案、スタブ、または Skill ツールを通じた UI／ロジックのコードなど、安価で粗削りながら具体的な成果物を作り、それを見て反応できるようにして、議論の精度を高めます。プロトタイプをアセットとしてリンクします。「どのように見えるべきか」や「どのように動作すべきか」が主な問いの場合に使用します。
• Grilling（HITL）：一度に一つずつ質問する会話です。デフォルトの種類です。必ず「grilling」を指定して Skill ツールを呼び出してください。
• Task（HITL または AFK）：意思決定を行う前に必要な手作業です。決めることも、プロトタイプも、調査もありませんが、完了するまで議論が進められない作業です。サービスに登録して API を評価できるようにする、アクセス権を用意する、データを移動してその形を確認できるようにする、といった作業です。これは意思決定ではなく実作業を行う唯一の種類であり、目的地に到達することではなく、意思決定の障害を取り除くことで存在意義を持ちます。エージェントだけでできる場合はエージェントが進めます（AFK）。そうでない場合は、人間に明確なチェックリストを渡します（HITL）。作業の完了時に解決し、その回答には実施内容と、後続のチケットが必要とする結果の事実（認証情報の保存場所、新しい URL、行数など）を記録します。

見通せない範囲

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

マップの Not yet specified セクションには、そのぼんやりとした見通しを記します。後で見直すべき問いや領域を記録します。これは目的地に向かう、まだ発見されていない領域です。ここにある内容はすべて対象範囲内ですが、チケットにできるほど明確ではありません。見通せる範囲に応じて、簡潔にも詳しくも記述してください。取り組みの進む方向を知りたい協力者にとって、道しるべにもなります。

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

• チケットにする場合：問いがすでに明確であれば、作業が妨げられていて今は着手できなくてもチケットにします。
• Not yet specified にする場合：まだそれほど明確に表現できない場合です。見通せない範囲を、あらかじめチケット単位に分割しないでください。そこはチケットより大まかな単位であり、その領域に差し掛かったとき、一つの部分から複数のチケットが生まれることも、何も生まれないこともあります。

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

対象外

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

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

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

呼び出し

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

マップを作図する

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

1. 目的地を定めます。 「grilling」を指定して Skill ツールを呼び出し、このマップが何を目指すのか、つまり仕様、決定、または変更を明確にします。目的地によってスコープが決まるため、最初に確定します。
2. フロンティアをマッピングします。 今度は幅優先で再び質問し、どれか1つの話題を深掘りするのではなく、全体にわたって掘り下げ、未決定事項と今すぐ着手できる最初のステップを明らかにします。これによって Fog が見つからない場合（目的地までの道筋がすでに明確で、全行程が1セッションで完了できるほど短い場合）は、マップは不要です。そこで止め、どのように進めたいかユーザーに尋ねます。
3. マップを作成します（ラベル wayfinder:map）。目的地とメモを記入し、これまでの決定事項は空のままにして、Fog を未指定に概略として記します。
4. 現時点で仕様を定められるチケットを子課題としてマップに作成し、その後、2回目のパスでブロック関係を設定します（課題同士を相互参照するには、先に ID が必要です）。このパスでは、実際の ID を使って相互参照も記入します。プレースホルダー #<n> は無関係な課題への自動リンクになります。ブロック関係を設定すると、チケットはフロンティアとブロック済みに整理されます。まだ仕様を定められないものは、Fog、つまり未指定セクションに残します。
5. 調査サブエージェントを起動します。 作成した research チケットごとに、サブエージェントを起動します。サブエージェントは Skill ツールを「research」で呼び出して並行して解決し、チケットからコンテキストポインターを取得したうえで、調査結果を使い捨ての research/<name> ブランチに記録します。ブランチはプッシュしますが、PR は作成しません。マージされることはありません。
6. ここで止めます。 作図は1セッションで行う作業であり、手作業でチケットを解決することはありません。

マップを使って作業する

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

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

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