wayfinder

ばらばらなアイデアがやってきました。1 回のエージェントセッションには大きすぎ、霧に包まれています。ここから目的地までの道筋は、まだ見えていません。Wayfinding とは、目的地に向かって突き進むのではなく、その道筋を見つけることです。このスキルでは、リポジトリのイシュートラッカーに共有マップとして道筋を描き、意思決定チケットに取り組みます。意思決定チケットとは、解決がビルドの実行に必要な作業単位ではなく、ひとつの決定となる問いです。ルートが明確になるまで、ひとつずつ解決していきます。

目的地は取り組みごとに異なり、その名前を決めることがマップを描く最初の作業です。名前によって、各チケットの内容も形作られます。反復して完成させる仕様の場合も、計画を始める前に確定すべき決定の場合も、データ構造の移行のようにその場で行う変更の場合もあります。マップはドメインに依存しません。エンジニアリング作業でも、コースのコンテンツでも、この形式に収まるものであれば扱えます。

実行ではなく計画

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

名前で参照する

マップも各チケットもイシューであり、名前、つまりタイトルがあります。人間が読むすべての箇所、たとえば説明文やマップの Decisions-so-far では、ID、番号、スラッグだけでなく、必ず名前で参照してください。#42, #43, #44 が並んでいても読めませんが、名前ならひと目で読めます。ID と URL もなくなるわけではありません。名前にリンクを埋め込みますが、それらは名前の代わりではなく、名前の中に含めてください。

マップ

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

マップはインデックスであり、保管庫ではありません。決定事項を一覧し、その詳細を記録したチケットを参照します。各決定が記載される場所はひとつだけ、つまりそのチケットです。そのためマップでは決定を繰り返さず、要約してリンクするだけにします。

マップ、その子チケット、ブロッキング関係、フロンティアのクエリが物理的にどこにあるかは、トラッカーによって異なります。 イシュートラッカーはすでに指定されているはずです。指定されていない場合は、/setup-leandrocfe-skills を実行してください。このリポジトリでの表現方法については、トラッカーのドキュメントの「Wayfinding operations」セクションを参照してください。トラッカーが指定されていない場合は、ローカルの Markdown トラッカーをデフォルトとして使用してください。

マップ本文

マップ全体を低解像度で記述し、セッションごとに一度だけ読み込みます。オープンチケットは一覧しません。それらはオープンな子イシューであり、クエリで取得します。

## Destination

<como é chegar ao fim deste mapa — a spec, decisão ou mudança que esta empreitada está buscando. Uma ou duas linhas; toda sessão se orienta por isso antes de escolher um ticket.>

## Notes

<domínio; skills que toda sessão deve consultar; preferências permanentes desta empreitada>

## Decisions so far



- [<título do ticket fechado>](link) — <resumo de uma linha da resposta>

## Not yet specified



## Out of scope

チケット

各チケットはマップの子イシューであり、トラッカーのイシュー ID がその識別子です。本文は問いであり、100K トークンのエージェントセッションに適した規模にします。

## Question

<a decisão ou investigação que este ticket resolve>

各チケットには wayfinder:<type> ラベルをひとつ付けます。ラベルは research、prototype、grilling、task のいずれかです（チケットの種類を参照）。

セッションでは、マップを担当する開発者を割り当てることでチケットを確保します。競合するセッションがそのチケットをスキップできるよう、作業を始める前に、まず割り当ててください。割り当て先が確保状態を表します。オープンで担当者がいないチケットは、未確保です。

ブロッキングには、トラッカーのネイティブな依存関係機能を使用します。これが重要なのは、フロンティアがトラッカーの UI 上に視覚的に表示されるためです。人間はマップを開かなくても、着手できるチケットを確認できます。ネイティブなブロッキング機能がないトラッカーに限り、本文中の慣例を代替手段として使用します。ブロッキングしているすべてのチケットがクローズされていると、そのチケットはブロック解除済みです。フロンティアとは、オープンで、ブロック解除済みで、未確保の子チケットのことであり、既知の範囲の端を指します。

回答は本文には含めません。解決時に記録します（マップに取り組むを参照）。チケットの解決時に作成したアセットは、イシュー内に貼り付けず、イシューからリンクしてください。

チケットの種類

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

• Research（AFK）：ドキュメント、サードパーティ API、ナレッジベースなどのローカルリソースを読み、意思決定に必要な事実を明らかにします。/research の subagent が解決します。現在の作業ディレクトリの外にある知識が必要な場合に使います。
• Prototype（HITL）：具体的で、手軽かつ粗削りな成果物を作り、それをもとに議論できるようにして、議論の精度を高めます。アウトライン、スケッチ、スタブ、または /prototype スキルを使った UI／ロジックのコードなどを作成します。プロトタイプをアセットとしてリンクします。「どのように見えるべきか」または「どのように動作すべきか」が中心的な問いである場合に使います。
• Grilling（HITL）：対話です。標準となるケースです。必ず /grilling と /domain-modeling のスキルを呼び出してください。
• Task（HITL または AFK）：意思決定を行う前に必要な手作業です。決めることも、プロトタイプを作ることも、調査することもありませんが、作業が完了するまで議論が進められない状態です。API を評価できるようにサービスに登録する、アクセス権を準備する、データ形式を確認できるようデータを移動する、といった作業が該当します。これは何かを実行する唯一の種類ですが、その価値は最終的な成果を届けることではなく、意思決定を可能にすることにあります。可能であればエージェントだけで進め（AFK）、そうでなければ人間に正確なチェックリストを渡します（HITL）。作業が完了した時点で解決とし、回答には、後続のチケットが依存する、実施した作業とその結果判明した事実（認証情報の保存場所、新しい URL、行数など）を記録します。

Fog of war

マップは_意図的に_不完全です。まだ見えていないものを描いてはいけません。進行中のチケットの先には fog of war（戦場の霧）があります。これは、いずれ必要になるとわかっていても、未解決の問いに依存しているため、まだ特定できない決定や調査が見通しにくくなっている状態です。チケットを解決すると、その先の霧が晴れ、今なら具体化できるものが新しいチケットとして一つずつ見えてきます。目的地までの道筋が明らかになり、チケットが残らなくなるまで続きます。

マップの Not yet specified セクションには、この見通しにくい状態を書き留めます。気がかりな問いや、後で見直す領域を記載します。これは目的地_へ向かう_、まだ発見されていないフロンティアです。ここにあるものはすべてスコープ内ですが、チケットにするにはまだ十分明確ではありません。見通しに応じて、簡潔にも詳細にも書いてください。取り組みがどこへ向かっているのかを読む協力者にとっての道しるべにもなります。

霧かチケットか？ 判断基準は、今その問いを正確に述べられるかどうかです。今すぐ答えられるかどうか_ではありません_。

• チケットにする場合：問いがすでに明確な場合です。ブロックされていて、まだ着手できなくてもかまいません。
• Not yet specified にする場合：まだその問いを明確に言い表せない場合です。霧をチケットサイズに細分化してはいけません。霧はチケットより大きく、フロンティアが近づいたときに、一つの領域から複数のチケットが生まれることも、チケットが一つも生まれないこともあります。

Not yet specified には、すでに決定したこと（Decisions so far）、すでに進行中のチケット、スコープ外のもの（次のセクション）を含めません。

スコープ外

霧は目的地 に向かって のみ積み重なります。目的地によってスコープが定まるため、その先の作業は スコープ外 です。霧ではなく、Not yet specified にも属しません。マップには独立した Out of scope セクションを設け、今回の 取り組みから意識的に除外した作業を記載します。そこに分類するのは明確さではなく、スコープです。

スコープ外の作業が段階的に進むことはありません。frontier は目的地で止まるため、再び対象になるのは目的地を再設定した場合だけです。その場合も、再開ではなく新たな取り組みとして扱います。

スコープ外と宣言するのはスコープを定める行為であり、道筋を進む一歩ではありません。既存のチケットが目的地の範囲外だと判明した場合——マッピング中にスコープが不適切だと分かった場合も、解決の結果明らかになった場合も——クローズします（クローズ済みのチケットは、間違いなく frontier の外にあります）。そして Out of scope セクションに、概要と対象外である理由を記し、クローズしたチケットへのリンクを付けます。そのチケットは Decisions so far には含めません。このセクションには実際にたどった道筋を記録するためです。スコープの境界は、その道筋の一歩ではありません。

呼び出し

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

マップを描く

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

1. 目的地を定めます。 /grilling と /domain-modeling のセッションを実行し、このマップが目指すもの——仕様、決定、または変更——を明確にします。目的地によってスコープが定まるため、最初に解決します。
2. frontier をマッピングします。 もう一度、今度は幅広く掘り下げます。1 つの筋道を深掘りするのではなく、空間全体に広がり、未決の判断事項と、すぐに着手できる最初のステップを明らかにします。霧が何も見つからない場合——目的地までの道筋がすでに明確で、道のり全体が 1 セッションで十分なほど小さい場合——マップは不要です。そこで止めて、今後どう進めるかをユーザーに尋ねます。
3. マップを作成します（label wayfinder:map）。Destination と Notes を記入し、Decisions-so-far は空のままにします。霧は Not yet specified に概要を記します。
4. 現時点で仕様を定められるチケットを作成します。マップの子 issue として作成し、その後、別の 2 回目の作業で blocking edge を接続します（issue 間で相互参照するには、先に ID が必要です）。edge を接続すると、チケットは frontier 上のものとブロックされているものに分かれます。まだ仕様を定められないものは、霧、つまり Not yet specified セクションに残します。
5. research subagent を起動します。 今作成した各 research チケットについて、/research subagent を起動して並行して解決し、調査結果を throwaway branch research/<name> に記録します。チケットから context pointer を付けます。
6. 止めます。マップを描くこと自体が 1 セッション分の作業です。手動で何かを解決することはありません。

マップに取り組む

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

1. マップを読み込みます。各チケットの本文ではなく、低解像度の概要です。
2. チケットを選びます。ユーザーが指定した場合は、それを使用します。指定がない場合は、フロンティアの先頭にあるチケットを順番に選びます。担当を確保し、作業を始める前に自分を担当者に設定します。
3. チケットを解決します。必要に応じてズームインし、関連するチケットやクローズ済みのチケットの全文をリクエストに応じて取得します。ブロック ## Notes に記載されたスキルを呼び出します。迷った場合は、/grilling と /domain-modeling を使用します。
4. 解決内容を記録します。回答を解決コメントとして投稿し、issue をクローズして、マップの Decisions-so-far にコンテキストへのポインターを追加します。
5. 新たに明らかになったチケットを追加し（作成してから接続）、回答によって具体的に記述できるようになった曖昧な点をすべてチケット化します。チケット化した各曖昧な点は Not yet specified から削除し、新しいチケットの中だけに残します。回答によって、チケット（現在のチケットまたは別のチケット）が目的の範囲を超えていると判明した場合は、ルート上で解決するのではなく、out of scope と宣言します。決定によってマップのほかの部分が無効になる場合は、それらのチケットを更新するか削除します。

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