tracer-wayfinder

Wayfinder

1 つのエージェントセッションには大きすぎ、進む道筋もまだ不明確なアイデアには、これを使用してください。Wayfinding では目的地を定め、リポジトリのイシュートラッカー上にマップを作成し、意思決定チケット（解決すべきものが実装作業の一部ではなく、決定である質問）に取り組み、道筋が明確になるまで進めます。

これは tracer フローへの状況に応じた導入手段であり、デフォルトの開始点ではありません。意思決定が 1 つのセッションに収まる機能には、代わりに /tracer-interview-me を使用してください。

計画し、実行しない

Wayfinder は計画を立てます。その目的地は、仕様作成の準備が整った意思決定の一覧です。各意思決定チケットは回答で終わります。作業を構築する前に決めるべきことが何も残っていなければ、マップは完成です。

構築に取りかかりたくなった時点で、目的地に到達しています。整理済みのマップを /tracer-to-spec に渡してください。複数セッションにまたがるマップを /tracer-implement に直接渡してはいけません。分散した詳細をまとめるステップが省かれてしまいます。

名前で参照する

すべてのマップとチケットにはタイトルがあります。説明文およびこれまでの決定事項では、イシューを単独の ID、番号、パス、スラッグではなく、リンク付きの名前で参照してください。識別子はリンク内に引き続き表示されますが、名前の代わりにはなりません。

マップ

マップは wayfinder:map ラベルを付けた 1 つのイシューです。トラッカーに記載されたローカル相当の方法でもかまいません。その意思決定チケットは、マップの子として作成します。

マップは索引であり、保管場所ではありません。意思決定を記録する場所は 1 か所だけです。つまり、チケットの解決内容です。マップには 1 行の要約とリンクだけを記載します。未完了チケットは、マップ本文にコピーせず、トラッカーの子チケット／フロンティア検索で見つけます。

このリポジトリのWayfinding の操作手順（マップの作成、子チケットの関連付け、ブロック、フロンティア検索、割り当て、解決、索引の更新）については、docs/agents/issue-tracker.md を読んでください。このファイルが存在しても操作手順が記載されていない場合は、マップを作成する前に /tracer-setup を実行して更新してください。トラッカーが設定されていない場合は、/tracer-setup に記載されたローカルの .tracer/ 規約を使用してください。ローカル状態を作成する前に git check-ignore -q .tracer を実行してください。無視対象になっていない場合は、リポジトリのルート .gitignore に /.tracer/ を追加してください。

マップ本文

## Destination

<One or two lines describing the spec-ready body of decisions this map must produce.>

## Notes

<Domain, skills each session should consult, and standing preferences for this effort.>

## Decisions so far



- [<resolved ticket title>](link) — <one-line gist of the answer>

## Not yet specified



## Out of scope

意思決定チケット

各意思決定チケットはマップの子として作成し、新しいエージェントセッション 1 回に収まる規模にします。

## Question

<The decision or investigation this ticket resolves.>

各チケットには、次のいずれか 1 つのタイプラベルを付けます。wayfinder:research、wayfinder:prototype、wayfinder:interview、wayfinder:task（またはローカルトラッカーの同等のフィールド）。

マップコーディネーターは、作業を始める前に、設定済みトラッカーの割り当てまたはステータス操作を使用してチケットを割り当てます。名前を指定したチケットはこのマップに属し、未完了かつブロックされておらず、未割り当てであるか、すでにこのワーカーに割り当てられていなければなりません。そうでない場合は停止します。ブロックには、利用できる場合はトラッカー固有の関連付けを使用します。フロンティアとは、マップに属する未完了でブロックされていない未割り当ての子チケットです。

ワーカーがフロンティアを検索してチケットの割り当てを競い合う状態にしないでください。並列セッションを開始する前に、1 人のコーディネーターが異なるチケットを割り当てます。回答は、解決コメントまたはローカルで同等の方法で記録します。アセットはチケットからリンクし、マップに貼り付けないでください。

チケットの種類

すべてのチケットは、担当者とリアルタイムで進め、担当者が自身の立場を代弁する HITL、またはエージェントだけで進める AFK のいずれかです。エージェントは HITL チケットで担当者側に回答することはありません。

• Research（AFK）：単純なリポジトリ検索ではなく、出典に裏付けられたメモが必要な質問に回答します。/tracer-research でバックグラウンドワーカーを1つ実行します。ワーカーは直接調査し、引用付きのメモを1つ返します。そのメモをチケットからリンクします。
• Prototype（HITL）：何かの見た目や動作をどうすべきかが問われているときに、反応を得るための簡素で粗削りな成果物を作成します。新しい /tracer-prototype セッションを使用し、/tracer-handoff で連携します。チケットから使い捨てのブランチまたはコミットをリンクします。答えはプロトタイプによって明らかになった判断であり、本番コードではありません。
• Interview（HITL）：デフォルトです。この1つのチケットに範囲を絞り、/tracer-interview-me の進め方に従います。各ラウンドで回答可能な論点をすべて、推奨回答とともに提示し、事実確認は委任して、判断は担当者に委ねます。このチケットがマップの一部である間は、このスキルの通常の /tracer-to-spec への引き継ぎに従わないでください。用語や永続的な判断が固まってきたら、/tracer-domain-modeling を適用します。
• Task（HITL または AFK）：判断を下す前に手作業が必要な作業です。アクセス権の付与、サービスへの登録、形状を確認するためのサンプルデータの移動などが該当します。行き先を実現するためではなく、判断を前に進める場合にのみ設けます。実施内容と、後続のチケットで必要になる事実を記録して解決します。

先が見えない領域

マップは意図的に未完成です。Not yet specified には、対象範囲内で今後浮上すると予想できるものの、まだ正確に表現できない質問を記載します。チケットを解決すると探索の最前線が先へ進み、その不明瞭な部分が、新しい判断チケットにできるほど明確になることがあります。

判断基準は回答可能かどうかではなく、質問が明確かどうかです。

• 質問を今すぐ正確に述べられるなら、別のチケットが前提になっていても チケット を作成します。
• 質問をまだ正確に述べられないなら、先が見えない領域 として残します。あらかじめ細分化しないでください。1つの不明瞭な領域が、後に複数のチケットになることも、チケットにならないこともあります。

不明瞭な領域がチケットになったら、その質問が1か所だけに記載されるよう、すぐに該当項目を削除します。

対象範囲外

不明瞭な領域は行き先に向かって広がります。その範囲を越える作業は Out of scope に記載します。Not yet specified に記載してはならず、新しいチケットになることもありません。

既存のチケットが行き先の範囲外だと判明した場合は、ルートに関する判断として扱わずにクローズします。理由を説明するリンク付きの行を Out of scope に追加します。Decisions so far には追加しないでください。

セッションと並行処理の不変条件

1人のチケットワーカーが回答できる判断チケットは1つだけです。各マップでは、常に1人の map coordinator だけが探索の最前線の割り当てとマップ本文の編集を担当します。並行して動くチケットワーカーは、それぞれ割り当てられた子チケットだけを更新し、マップ差分を返します。コーディネーターはそれらの差分を順番に適用します。

マップ作成セッションでマップを作成し、各要素を接続します。複数のAFK調査ワーカーを並行して起動できます。各ワーカーには、事前に割り当てたチケットを1つだけ渡し、返された回答を記録します。これは複数のワーカーセッション間での並行処理であり、1人のワーカーのコンテキストで複数の質問を扱うものではありません。

ワーカーが応答しなくなっても、そのチケットの割り当ては維持されます。コーディネーターが割り当てを解除または変更できるのは、そのセッションがすでにアクティブでないと確認した後だけです。それを確認できない場合は、担当者に尋ねてください。同じマップに対して、チケットに割り当てられていないコーディネーターセッションを2つ同時に実行してはなりません。

起動方法

マップを作成する

ユーザーが大まかなアイデアをもとに /tracer-wayfinder を実行します。

1. 目的地を定めます。 tracer のフロンティアラウンドの進め方と /tracer-domain-modeling を使い、目的地を絞ったインタビューを行います。チケットを作成する前に、このマップがどこへたどり着くためのものかを決めます。目的地によってスコープが決まります。
2. 幅優先でマッピングします。 1つのテーマを深掘りするのではなく、全体を見渡しながら進めます。現時点でチケット化できる具体的な決定事項、そのブロック関係、さらに先にある大まかな不明点を明らかにします。通常の /tracer-interview-me とは異なり、このセッションではチケット化できる問いまでで止め、ツリー全体は解決しません。不明点がなく、すでに1回のセッションで経路をたどれる場合は、マップを作成する前に終了し、代わりに /tracer-interview-me で続けるか確認します。
3. マップを作成します。 Destination と Notes を記入し、Decisions-so-far は空のままにして、残りの不明点を Not yet specified の下に書き出します。
4. 作成してから依存関係を設定します。 現時点で問いが具体的な決定チケットをすべて作成し、マップの子チケットにします。2回目のパスですべてのチケットに ID が付与された後、ブロック関係を追加します。まだ具体化されていないものはすべて Not yet specified に残します。
5. フロンティア調査を割り当てます。 新しいフロンティアを照会し、ブロックされていない調査チケットをそれぞれ割り当ててから、作業を依頼します。チケットごとに1人のワーカーを起動し、低解像度のマップ、完全な Question、明示的なキャプチャーブランチを渡して /tracer-research を実行します。ブランチに成果物を保存する場合は、分離されたワークツリーを使用します。各ワーカーは直接調査し、固有の research/<map-slug>/<ticket-slug> ブランチに引用付きのノートを1つ書き、回答、コンテキストポインター、## Map delta を返します。マップは編集しません。バックグラウンドワーカーまたは分離環境を利用できない場合は、チケットをオープンのまま残し、新しい AFK セッションに引き継ぎます。
6. 返された調査結果を順番に記録します。 各ワーカーの作業が完了したら、コーディネーターが回答、成果物へのポインター、Map delta を子チケットに投稿してチケットをクローズし、作業ステップ5と同じインデックス／不明点／スコープ／新規チケットのルールを使って delta を適用します。ローカルの .tracer/ マップを使用する場合、分離されたワークツリーからは Git で無視される状態を参照できないため、マップファイルやチケットファイルに触れるのはコーディネーターだけです。調査がこのセッションをまたぐ場合、次のコーディネーターは新しい作業を割り当てる前に、完了した成果を記録して適用します。
7. 停止します。マッピングでは HITL チケットへの回答は行いません。

マップに沿って作業する

ユーザーは、マップの URL、番号、またはローカルパスを指定して /tracer-wayfinder を呼び出します。チケット名の指定は任意です。

1. 低解像度のマップを読み込み、Destination と Notes を確認します。コーディネーターモードでは、解決済みの各子チケットを Decisions so far と Out of scope に照らして比較します。不足している項目があれば、作業を割り当てる前に整合させます。
2. チケットを検証して選択します。 ユーザーが指定したチケットは、このマップに属し、オープン状態で、ブロックされておらず、担当者が割り当てられていない必要があります。ただし、コーディネーターがすでにこのワーカーに割り当てている場合は除きます。条件を満たさない場合は停止し、その理由を報告します。チケットが指定されていない場合、コーディネーターは最初のフロンティアチケットを選び、詳細な確認や議論に進む前に担当者を割り当てます。
3. 解決します。 必要に応じて、関連チケットやアセットを詳しく確認します。Notes に記載されたスキルに従います。特に指定がなければ、前述のチケット単位のインタビューとドメインモデリングの進め方に従います。
4. 子チケットの解決内容を記録します。 回答と、それに伴うインデックス、fog、スコープ、新規チケットの変更内容を正確に記述した ## Map delta を作成します。共有トラッカーでは、ワーカーが両方を投稿して子チケットをクローズします。ローカルの .tracer/ マップでは、ワーカーが両方を返し、コーディネーターが調整用チェックアウトに記録します。並行して作業するチケットワーカーはここで停止し、マップ本文は編集しません。
5. コーディネーターとしてマップを進めます。 完了した差分を一度に1つずつ適用します。関連する gist をそれぞれ Decisions so far に追加し、新たに明確になったチケットを作成してから関連付け、解消した fog を取り除き、Destination を超える作業を Out of scope に移し、無効になったチケットを更新するか Out of scope として扱います。これにより、クローズ済みのすべての子チケットの位置づけを明確にします。チケットワーカーがマップ本文を置き換えることはありません。
6. 完了を確認します。 すべての子チケットを再確認し、解決済みの各子チケットが Decisions so far または Out of scope に記載されていることを確認します。オープン、担当者割り当て済み、または進行中の意思決定チケットがなく、インデックスに記載されていない解決済みの子チケットもなく、Not yet specified が空の場合にのみ、マップは完了です。その後、次の文言で引き継ぎます：Invoke /tracer-to-spec with the cleared map <URL-or-path>.

各マップにつき、コーディネーターセッションは1つだけ実行してください。フロンティアチケットを並行して作業するには、コーディネーターが先に別々のチケットを割り当ててから、担当チケットを明示したワーカーセッションを起動または引き継ぎ、その後、返された差分を順番に適用します。