wayfinder

Wayfinder — 道を見つけ、目的地へ突き進まない

大きなアイデアがふと浮かびました。ひとつのエージェントセッションには大きすぎ、霧に包まれています。ここから目的地までの道は、まだ見えていません。Wayfinding とは、その道を探すことであり、目的地へまっすぐ突き進むことではありません。このスキルでは、issue 台帳上に地図として道を描き、そこにある意思決定チケットを一つずつ処理します。それぞれのチケットは、ビルド作業の一部分ではなく、答えがひとつの決定となる質問です。目的地までの道が明確になり、決めることがなくなるまで続けます。

これは /propose よりも前の段階です。propose は作業の形がすでにわかっていることを前提とします。wayfinder は、まだわかっていないときに使います。

WHAT

目的とコンテキスト

• 目的： 大きく、まだ不明瞭な作業のかたまりについて、目的地までの道を見つけます。issue 台帳上に意思決定チケットの地図を作成し、道が明確になって決めることがなくなるまで、各チケットを解決します。
• トリガー（使用するタイミング）： 形がまだ明確でない大きなアイデアがあるとき、/propose よりも前に手動で呼び出します。手動呼び出し専用（disable-model-invocation: true）。
• 対象外： 成果物やビルドを生成しません（それは /propose の後です）。HITL チケットで人間側の回答を代わりに解決しません。霧をあらかじめチケットに切り分けません。目的地より先の作業は解決しません（スコープ外です）。

メンタルモデル

漠然としたアイデア → Destination → 地図（wayfinder:map issue、インデックス） → 意思決定チケット（子 issue、ブロッキングエッジ） → フロンティア → チケットを一つ解決 → Decisions-so-far ＋ 霧を晴らす → … → 道が明確になる → /propose に引き継ぐ。

実行ではなく計画

Wayfinder はデフォルトで計画を行います。それぞれのチケットでひとつの決定を解決し、誰かが作業を始める前に道が明確になり、決めることがなくなった時点で地図は完成です。実行に取りかかりたいという衝動は、たいてい地図の端に到達し、/propose に引き継ぐタイミングが来たという合図です。成果物ではなく、決定を生み出します。

ID ではなく名前で呼ぶ

地図もチケットもそれぞれひとつの issue なので、名前、つまりタイトルがあります。読者向けのあらゆる記述（説明、Decisions-so-far）では、むき出しの ID ではなく、その名前で呼びます。#42, #43, #44 と並べられても読めませんが、名前ならすぐに理解できます。ID とリンクはなくなるわけではありません。名前がリンクを包み込みます。ただし、ID とリンクは名前の中に入り、名前の代わりにはなりません。

4 種類のチケット

各チケットは HITL（人間が回答）または AFK（エージェントが単独で実行）です。HITL チケットは人間とのやり取りを通じてのみ解決します。エージェントが人間側の代わりをすることは決してありません。自分で質問し、自分で答えるエージェントのグリリングは、このルールに反しています。

• research（AFK）— ドキュメント／API／ナレッジベースを調べ、決定を待っている 事実 を明らかにします。/research（または /agent-reach）サブエージェントで解決します。現在のディレクトリの外にある知識が必要なときに使います。
• prototype（HITL）— 具体的なたたき台を示して反応を引き出し、話し合いの解像度を高めます。アウトライン、草稿、スタブ、UI、ロジックなどが該当します。「どのように見えるか」／「どのように動作するか」が主な質問のときに使います。
• grilling（HITL）— 一問ずつ進める対話です。デフォルトの種類です。
• task（HITL または AFK）— 決定を可能にする前に完了しておく必要がある、人間の手作業です。API を確認するためのサービス登録、アクセス権の取得、データの移行による実態の把握などが該当します。唯一の、決めるのではなく実行する種類です。成果物を納品するためではなく、決定を可能にするための作業なので、ここに位置づける価値があります。

フォグ・オブ・ウォー

地図は意図的に不完全です。まだ見えていないものは描かないでください。進行中のチケットの外側には霧があります。いずれ必要になるとわかっていても、未解決の質問に依存しているため、まだ具体的な形にできない決定がぼんやり見えています。チケットをひとつ解決するたびに、その先の霧を晴らし、新しいチケットとして確定できるようになった項目をひとつずつ追加します。目的地までの道が明確になるまで続けます。

霧か、チケットか？ 判断基準は、今この時点で質問を正確に定義できるかです。答えられるかどうかではありません。

• 質問が明確なら、チケットにします。ブロックされていて実行できない場合も同様です。
• 正確に定義できない場合は、Not yet specified にします。霧をあらかじめチケットサイズの断片に切り分けないでください。霧はチケットよりも粗いものです。フロンティアがそこに達したとき、ひとつの領域が複数のチケットとして確定することもあれば、ひとつも確定しないこともあります。

対象外

霧は目的地に向かってだけ集めます。目的地が範囲を固定するため、その範囲を超えるものは対象外です。霧ではなく、Not-yet-specifiedにも属しません。独立した項目があり、今回の取り組みから意識的に除外するものです。対象外が解決済みになることはありません。既存のチケットが目的地の先にあると判明した場合は、クローズしてOut-of-scopeに1行残し、進行中に解決しないでください。

入力と出力の契約

	Field	Required?	意味
In	大まかなアイデア	あり（Chartモード）	道筋を見つける対象
In	マップ（issue wayfinder:map）	あり（Workモード）	作成済みのマップ
In	具体的なチケット	なし（Workモード）	指定がなければ、最初のフロンティアチケットを取得
Out	マップissue＋子issue＋ブロッキングエッジ	Chart	Destination、Not-yet-specifiedの霧の下書き、空のDecisions-so-far
Out	1件のチケットをclaim→解決→クローズ＋Decisions-so-far内のポインター	Work	新たに見つかったチケット／解決済みになった霧／更新済みの対象外を含む

ルールと機能

• RULE-01（MUST）：手動呼び出しのみ（disable-model-invocation: true）— wayfinderはユーザーが意図的に実行するアクションであり、モデルが自動的に実行するものではありません。[[skill-craft]]を参照してください。
• RULE-02（MUST）：計画し、実行しない — 決定を生み出し、成果物は生み出しません。実行に移りたくなったら、マップの端に到達しています。/proposeに引き継いでください。
• RULE-03（MUST）：1セッションにつき1チケット（researchを除く）、かつ作業前にclaim（frontier.pyとledgerのclaim欄を使用）。
• RULE-04（MUST）：Ledgerが信頼できる情報源であり、リモートトラッカーはミラーです。このリポジトリでの表現については[[issue-tracker]]を参照してください。
• 機能：ledger上のissueの読み書き（作成、ブロッキングエッジの接続、claim、クローズ）、フロンティアの照会、HITLチケットに関するユーザーとのライブ会話、並行してresearchするsubagentの起動。

失敗時の境界

• フロンティアを描いても霧が見つからない → 道筋は明確で、マップは不要です。停止して、次にどう進めたいかユーザーに尋ねてください。
• HITLチケットに回答者がいない → blocked。エージェントが代わりに回答してはいけません。
• 別のセッションがチケットをclaim済み → 解決せず、別のフロンティアチケットを選択してください。
• 解決の結果、目的地の先にあると判明 → チケットをクローズし、Out-of-scopeに記録してください（そのチケットはcancelled）。
• 実行に移りたくなった → マップの端に到達しています。/proposeに引き継いでください。

HOW

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	アイデア	（Chart）/grilling＋/domain-modelingを通じて目的地に名前を付ける	Destinationを1文で	—
W02	judgment	Destination	（Chart）幅優先でフロンティアを描く	開始するかどうかの判断＋最初の一歩	霧がなければ停止し、ユーザーに尋ねる
W03	effect	W01–W02	（Chart）マップとピン留め可能なチケットを作成し、2段階目のブロッキングエッジを接続	map issue＋子issue	—
W04	effect	researchチケット	（Chart）research用subagentを並行して起動し、その後停止	ポインター付きの発見事項	—
W05	deterministic	マップ	（Work）マップを読み込み、チケットを選択（ユーザー指定、またはfrontier.py --map <id>）、先にclaim	claim済みチケット	claim済みなら別のチケットを選択
W06	judgment	チケット	（Work）解決する。必要に応じて詳細を掘り下げ、HITLならユーザーに尋ねる	解決策	行き詰まったら/grilling＋/domain-modeling
W07	effect	解決策	（Work）resolutionを記録し、issueをクローズ（status: done）、Decisions-so-farに追記し、新しいチケットを作成／霧を解決済みにする／対象外に分類する	更新済みマップ	—

各ステップの詳細（W01–W07の信頼できる情報源）：

モードは2つです。どちらも、researchを除き、1セッションで解決するチケットは決して1件を超えません。

地図を描く（マップを作成する）

ユーザーが曖昧なアイデアを持ち込んだ場合。

1. 目的地を定めます。 /grilling + /domain-modeling（利用可能な場合）を実行し、この目的地が何を目指すのかを明確にします。目的地によって範囲が固定されるため、最初に確定します。→ 完了条件： 以降のすべてのセッションの指針となる「目的地」を一文で示せること。
2. フロンティアを描きます。 さらにグリルし、幅広く探ります。1つの流れを深掘りするのではなく、空間全体に広げ、未決定の項目とすぐに着手できる最初のステップを洗い出します。曖昧な点が出てこない場合は、道筋が明確なので地図は不要です。そこで止め、次にどう進めるかユーザーに尋ねます。
3. 地図を作成します（ラベル wayfinder:map）：目的地とメモを記入し、「これまでの決定」は空欄にして、曖昧な点を「未指定」に書き出します。
4. ピン留めできるチケットを子 issue として作成し、2回目のパスでブロッカーのエッジをつなぎます（相互に参照するには issue の ID が先に必要です）。→ 完了条件： ピン留め可能なチケットがすべて作成され、ピン留めできない項目は曖昧な点として残っていること。
5. 調査用のサブエージェントを起動します。 各 research チケットにつき1つのサブエージェントを割り当てて並行して解決し、調査結果を記録して、チケットからコンテキストへのポインターを付けます。
6. 停止します。地図の作成は1セッションで行う作業であり、チケット自体は解決しません。

地図に沿って進める

ユーザーが地図を持ち込んだ場合。チケットの指定は任意です。指定がなければ、次に解決する項目を選ぶのはユーザーではなくあなたです。

1. 地図を読み込みます（低解像度のビューで、すべてのチケット本文ではありません）。
2. チケットを選びます。ユーザーが指定した場合はそれを使います。指定がなければ、最初のフロンティアチケット（frontier.py --map <id>）を選びます。Claim します。作業を始める前に、claim 欄を記入します。
3. 解決します。必要に応じてズームインします。要求された場合は関連チケットの全文を取得し、メモに明記されているスキルを呼び出します。行き詰まった場合は /grilling + /domain-modeling を使います。
4. 解決内容を記録します。解決内容を resolution として投稿し、issue をクローズし（status: done）、地図の「これまでの決定」にポインターを1つ追加します。
5. 新たに判明したチケットを追加します（作成してから接続）。解決によってピン留め可能になった曖昧な項目は昇格させ、「未指定」から削除します。解決によって目的地より先にあるチケットが判明した場合は、スコープ外として除外します。解決によって地図の別の箇所が否定された場合は、そのチケットを更新または削除します。

分岐

ID	種類	条件	動作	スキップ／失敗	再合流
B01	user_optional	ユーザーが既存の地図を持ち込む	Chart（W01–W04）ではなく、Work through the map モード（W05–W07）を使う	—	1つのチケットを処理してセッション終了
B02	conditional_required	チケットが research 型	サブエージェント /research（または /agent-reach）で解決し、複数チケットの並行処理が可能	—	W07
B03	conditional_required	チケットが HITL（prototype/grilling/task-HITL）	人とのリアルタイムなやり取りを通じてのみ解決する	人がいない場合 → blocked	W07
B04	recovery	解決によって地図の別の箇所が否定された	そのチケットを更新または削除する	—	W07

検証と停止条件

Chart は W04 の後に停止します（チケット自体は解決しません）。Work はちょうど1つのチケットの後に停止します（research を除く）。目的地までの道筋が明確で、決定することが残っていない場合、地図は完成です。/propose に引き継ぎます。次のチケットは frontier.py と claim 欄で決定し、推測しません。

例

• 成功例： 「/wayfinder overstack を multi-model dispatch に切り替えて」→ グリルして目的地を一文で定め、フロンティアから3つのチケット（provider API に関する research 1件、grilling 2件）が明らかになる → wayfinder:map の地図と3つの子 issue を作成し、2回目のパスでブロッカーのエッジをつなぎ、調査用サブエージェントを1つ起動 → 停止。
• 境界／失敗例： 「/wayfinder 」だが、フロンティアのチケットが grilling（HITL）で、ユーザーが不在 → blocked。エージェントが自分の質問に自分で答えることはなく、同じセッションで2つ目のチケットも解決しません。

リファレンス — 地図

地図は ledger 上の1つの issueです（ラベル wayfinder:map）。チケットはその子 issue です。地図はインデックスであり、保管庫ではありません。完了した決定を列挙し、詳細を保持するチケットを参照します。1つの決定は1か所（そのチケット）にのみ存在します。地図では決定を繰り返さず、要約とリンクだけを記載します。地図、子チケット、ブロッカーのエッジ、フロンティアクエリの保存場所はトラッカーによって異なります。[[issue-tracker]] §「Wayfinding operations」を参照してください。

地図の本文（セッションごとに1回読み込みます）：

## Destination
<đi tới cuối bản đồ này trông như thế nào — spec, quyết định, hay thay đổi mà nỗ lực này tìm đường tới. Một hai dòng; mỗi phiên định hướng vào nó trước khi chọn ticket.>

## Decisions so far

- [<tên ticket đã đóng>](link) — <gist một dòng của lời giải>

## Not yet specified


## Out of scope

チケットは子 issue で、本文は1セッションで扱える大きさの質問です。

## Question
<quyết định hay điều tra mà ticket này giải>

Origin

• Chưng cất từ mattpocock/skills — skills/engineering/wayfinder/SKILL.md (clone scratchpad/mattpocock-skills/, 2026-07-15).
• Absorb qua /propose → 150726-mattpocock-absorb (T8), task T-260715-01. Đứng trên hạ tầng ledger T6/T7.
• Commit: (verify-before-commit điền)