wayfinder

緩やかなアイデアが浮かびました。それは大きすぎて単一の agent session には収まらず、fog に包まれています。ここから destination までの道は、まだ見えていません。Wayfinding の目標は、その道を見つけることであり、destination に向かって突き進むことではありません。この skill は、repo issue tracker 上に shared map として道筋を描き、decision tickets（実行する build slices ではなく、解決に decision が必要な問題を扱います）を一つずつ処理して、道筋が明確になるまで進めます。

effort によって destination は異なります。それに名前を付けることが charting の最初の作業であり、すべての ticket の形を決めます。引き継いで反復するための spec、planning 前に確定しなければならない decision、あるいは data-structure migration のようにその場で完了する change かもしれません。Map は分野を問いません。engineering work、course content、またはこの形に合うものであれば何でも使えます。

計画のみで、実行しない

Wayfinder はデフォルトで planning に使います。各 ticket は一つの decision を解決します。誰かが作業を始める前に決めるべきことがなくなり、道筋が完全に明確になったとき、map は完成です。すぐに作業したいという衝動は、たいてい map の端まで来ていて、引き継ぐべきだという合図です。effort の Notes でこのデフォルトを上書きすれば、execution も map に含められます。そうでなければ、成果物ではなく decisions のみを作ります。

名前で参照する

各 map と各 ticket は issue なので、それぞれ name、つまり title があります。説明文や map の Decisions-so-far を含む、人が読むすべての内容では、裸の id、number、slug だけを記すのではなく、name で参照してください。#42, #43, #44 と並べても読みにくいですが、name なら一目でわかります。Id と URL はなくならず、name のリンク内に含まれますが、name の代わりとして単独で使うことはありません。

共有マップ

Map は、この repo issue tracker 上にある wayfinder:map label 付きの単独 issue であり、canonical artifact です。その tickets は map の child issues です。

Map は index であり、store ではありません。すでに行った decisions を列挙し、詳細が記録された tickets を示します。したがって、decision の記録場所は一つだけ、つまりその ticket です。Map では詳細を繰り返さず、要旨とリンクだけを示します。

Map、child tickets、blocking、frontier queries の具体的な表現方法は tracker によって異なります。 Issue tracker はすでに用意されているはずです。ない場合は、ユーザーに /setup-matt-pocock-skills を実行してもらってください。tracker doc の「Wayfinding の操作」セクションを確認し、この repo での表現方法を把握してください。tracker がない場合は、デフォルトで local-markdown tracker を使用します。

Map 本文

Map は全体を低解像度で示すもので、各 session で一度読み込みます。Open tickets は map に列挙しません。それらは open child issues であり、query を使って見つけます。

## 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

Tickets

各 ticket は map の child issue であり、tracker の issue id がその identity です。Body は、100K token の agent session 1 回で扱える規模の質問です。

## Question

<the decision or investigation this ticket resolves>

各 ticket には wayfinder:<type> label を付けます。値は research、prototype、grilling、task です（Ticket Types を参照）。

Session は、作業を始める前に、まず ticket をその driving map の dev に assign することで ticket を claim します。これにより、並行する sessions はその ticket をスキップします。この assignee が claim を示します。open かつ unassigned の ticket が unclaimed です。

Blocking には tracker の native dependency relationship を使います。これは重要です。tracker UI が frontier を可視化するため、人間は map を開かなくても、どの ticket に取りかかれるかを確認できます。tracker に native blocking がない場合に限り、body convention に切り替えてください。ある ticket の blockers がすべて閉じると、その ticket は unblocked です。frontier とは、open、unblocked、unclaimed の child tickets、つまり既知の世界の境界です。

回答は body に書かず、解決時に記録します（マップに沿って進めるを参照）。ticket の解決時に作成された assets は、body に貼り付けず、issue からリンクします。

Ticket の種類

各 ticket は HITL（human in the loop。自分の言葉で発言できる人間と一緒に進める）または AFK（agent が単独で進める）のいずれかです。HITL ticket はライブでのやり取りを通じてのみ解決できます。agent が人間に代わって回答してはいけません。grilling agent が自問自答した時点で、その agent はすでに失敗しています。

• Research（AFK）：documentation、third-party APIs、knowledge bases などの local resources を読み、ある decision が待っている事実を明らかにします。Skill ツールを呼び出し、research を指定する subagent に解決を任せます。現在の working directory の外にある知識が必要な場合に使います。
• Prototype（HITL）：outline、rough take、stub などの安価で大まかな具体的 artifact を使って、議論の fidelity を高めます。または、Skill ツールを呼び出し、prototype を指定して UI/logic code を書きます。Prototype は asset としてリンクします。中心となる質問が「どのように見せるべきか」または「どのように動作させるべきか」の場合に使います。
• Grilling（HITL）：Conversation です。デフォルトの種類です。Skill ツールを必ず 2 回呼び出し、それぞれ grilling と domain-modeling を指定します。
• Task（HITL または AFK）：decision を下す前に完了する必要があるものの、それ自体には decide、prototype、research することがない manual work です。たとえば、API を評価するためのサービス登録、アクセス権の設定、データの形を把握するためのデータ移動などです。do を行う唯一の種類であり、destination を提供するためではなく、decision を可能にするために存在します。agent が単独で実行できる場合は AFK とし、そうでなければ人間向けに正確な checklist を用意します（HITL）。作業が完了したら resolved にします。回答には、実施した内容と、後続の tickets が依存する事実（credentials の場所、新しい URLs、row counts など）を記録します。

霧

Map は 意図的に 不完全です。まだ見えていないものを描いてはいけません。Tickets の外側にあるのが霧です。いずれ現れると感じられる decisions や investigations ですが、まだ解決されていない問いの上に浮かんでいるため、現時点では固定できません。ticket を解決すると、その前方にある霧の一部が晴れ、今なら説明できる問いが新しい tickets に昇格します。目標への道筋が明らかになり、tickets が残らなくなるまで、一度に一つずつ進めます。

Map の Not yet specified セクションには、こうしたぼんやりした視野を記録します。疑問に思っていることや、後で再訪する領域です。destination へ続く、まだ探索されていないフロンティアです。すべてスコープ内ですが、ticket にできるほど明確ではありません。視野が許す粒度で記述してください。また、協力者がこの effort の進み方を把握するための道しるべにもなります。

霧か ticket か？ 判断基準は、今その問いに答えられるかどうかではなく、問いを明確に説明できるかどうかです。

• Ticket にする場合： 問いが明確であること。blocked で、今は対応できない場合も含みます。
• Not yet specified にする場合： まだそれほど明確に説明できないこと。霧をあらかじめ ticket サイズに切り分けてはいけません。霧は ticket より粗く、フロンティアに到達した時点で、霧の一部が複数の tickets に昇格することも、何も生まないこともあります。

Not yet specified には、すでに決定された内容（Decisions so far）、すでに live ticket になっている内容、スコープ外の内容（次のセクション）は含めません。

スコープ外

霧は destination へ向かう方向にのみ集まります。Destination はスコープを固定するため、その範囲を超える作業は スコープ外 であり、霧でも Not yet specified の対象でもありません。これは map の独立した Out of scope セクションに記載します。この effort の範囲から意図的に除外した作業です。ここに含めるかどうかを決めるのは明確さではなく、スコープです。

スコープ外の作業が昇格することはありません。フロンティアは destination で止まります。Destination を描き直した場合にのみ、その作業が再び対象になります。その場合は再開ではなく、新しい effort とする必要があります。

何かをスコープから除外するのはスコープ設定の行為であり、ルート上の一歩ではありません。既存の ticket が destination の範囲外だと判明した場合（マップ作成時に誤ってスコープ内に含めていた場合や、解決によって判明した場合）は、close してください（closed ticket は明確にフロンティア上にありません）。そして Out of scope セクションに、その要旨とスコープ外である理由を一行で記し、closed ticket へのリンクを追加してください。Decisions so far には記載しないでください。そこに記録するのは実際にたどった道筋のみであり、スコープの境界は道筋上の一歩ではありません。

呼び出し方

モードは二つあります。どちらの場合も、1 回の session で resolve する ticket は 1 つまでです。research tickets は除きます。

マップを描く

ユーザーが漠然としたアイデアを持ち込んで呼び出します。

1. 目的地を定めます。 Skill ツールを 2 回呼び出し、それぞれ grilling と domain-modeling を指定して、map が見つけるべき spec、decision、または change を特定します。Destination がスコープを固定するため、まずそれを解決します。
2. フロンティアをマップします。 今度は 幅優先 で、もう一度 grill します。一つの thread を深掘りするのではなく、空間全体をカバーして、未決定事項と今すぐ始められる最初のステップを浮き彫りにします。霧がなければ、道筋は明らかで、journey 全体を 1 回の session で完了できるため、map は不要だと伝えます。停止して、次にどう進めるかユーザーに尋ねます。
3. map を作成します（label wayfinder:map）。Destination と Notes を記入し、Decisions-so-far は空のまま、霧を Not yet specified に描き込みます。
4. 今すぐ明確にできる tickets を作成し、map の child issues として登録します。その後、blocking edges を 2 回目の作業で接続します（issues は互いを参照するための ids が必要です）。接続すると、tickets はフロンティアと blocked に分かれます。今はまだ説明できない内容はすべて Not yet specified に残します。
5. research subagents を起動します。 作成した各 research ticket について、research を指定して Skill ツールを呼び出す subagent を並行して 1 つずつ起動し、ticket を解決します。findings は一時的な research/<name> branch に保存し、ticket には context pointer を残します。
6. 停止します。マップ作成は 1 session で行う作業です。この session 中に手動で tickets を resolve してはいけません。

マップに沿って進める

ユーザーが map（URL または number）を指定して呼び出します。Ticket は 任意 です。ticket が指定されていない場合は、次の decision を選ぶのはユーザーではなくあなたです。

1. map を読み込みます。各 ticket の body ではなく、低解像度のビューを使います。
2. ticket を選びます。ユーザーが指定した場合はそれを使い、そうでなければ、順番に最初のフロンティア上の ticket を選びます。作業を始める前に、Claim it：自分に割り当てます。
3. ticket を解決します。必要に応じて zoom し、関連する ticket または closed ticket の完全な body は必要な場合にのみ取得します。## Notes block で挙げられている skills を呼び出します。不確かな場合は、Skill ツールを 2 回呼び出し、それぞれ grilling と domain-modeling を指定します。
4. resolution を記録します。回答を resolution comment として投稿し、issue を close して、map の Decisions-so-far に context pointer を追加します。
5. 新たに浮かび上がった tickets を追加します（create-then-wire）。答えが明らかになった霧は ticket に昇格させ、Not yet specified から昇格した patch を一つずつ削除し、新しい ticket としてのみ残します。回答によって、この ticket または他の ticket が destination の範囲外だと分かった場合は、ルートの一部として解決するのではなく、スコープ外と判定します。この decision によって map の他の部分が無効になる場合は、それらの tickets を更新または削除します。

ユーザーが unblocked tickets を並行して進めることもあるため、他の sessions が同時に tracker を編集することを想定してください。