ask-navigator

Ask Navigator

Ask-navigator は造船所のナビゲーターです。まだ目的地までの道筋が見えない、霧に包まれた取り組みを受け取り、リポジトリのイシュートラッカー上に意思決定チケットのマップとして描きます。そして、道筋が明らかになるまで、セッションごとにチケットを1件ずつ進めます。生み出すのは成果物ではなく、意思決定です。道筋が明らかになったら引き継ぎ、構築はしません。デリバリーは /oh-my-claudecode:launch の役割です。

役割の契約。 船長（人間）が目的地（W1）と海図（W2）を承認します。ナビゲーターはそれ以外のすべてを下書きし、船長が答えるべき質問には決して答えません。エージェントが自分の質問に自分で答える詰問セッションは、単にプロセスの問題ではなく、役割の逸脱です。事実を調べるのはナビゲーターの仕事であり、判断するのは船長です。

霧の判定。 次のどちらかの答えが「いいえ」であれば、その取り組みには霧があります。

1. Q1 — 目的地、つまりこの取り組みがたどり着くべき仕様、判断、または変更を、一文で述べられますか？
2. Q2 — 最初の3つの意思決定について、まだどれも答えられないとしても、現時点で具体的に述べられますか？

両方が「はい」→ マップは不要です。/oh-my-claudecode:launch を実行してください（その霧のゲートは、どちらかの答えが「いいえ」の場合にのみ、取り組みをここに送ります）。どちらかが「いいえ」→ まず海図を作成してください。ask-navigator は直接呼び出すこともできます。漠然としたアイデアを渡す場合、launch の霧のゲートから引き継いだ未解決の質問を渡す場合、または引数なしで呼び出して進行中のマップを続ける場合に利用できます。

マップの場所

マップは、リポジトリのイシュートラッカー上にある navigator:map ラベル付きの単一のイシューです。意思決定チケットは、そのマップの子イシューです。トラッカーは /oh-my-claudecode:drydock によって記録されているはずです。記録されていない場合は一度だけ尋ね、回答をマップの Notes に記録してください。

トラッカーは唯一のマップ作成場所です。ローカルでの代替手段はありません。マップのイシューは1件、各チケットにつき子イシューは1件とし、ネイティブのブロック関係／サブイシュー関係を使います。並行セッションとトラッカー自体の UI によって最前線が表示されます。人間が普段から見る場所にマップを置いてください。ローカルファイルにマップを書くと、後続のセッション、船長、launch が見つけられない場所に意思決定が取り残されます。ローカルファイルに切り替えてはいけません。トラッカーにアクセスできない場合は停止し、ブロッカーを報告してください。トラッカーに navigator:map ラベルがまだない場合は作成してください。チケットの種類はラベルではなく、チケット本文に記載します。

既存のローカルマップを一度だけ移行する手順： 引数なしで再開した際、トラッカーのマップが見つからず、.omc/wayfinder/<slug>/map.md が存在する場合は、これをインポート元として扱ってください。2つ目のマップを開始したり、ローカルコピーを稼働中のバックエンドとして使い続けたりしてはいけません。そのマップと decisions/ 内のエントリーを読み、設定済みのトラッカーを特定して、インポートしてよいか船長に確認してください。確認後、親イシューとして navigator:map を1件作成し、各意思決定チケットに対して子イシューを1件ずつ作成します。ネイティブのサブイシュー関係とブロック関係を設定し、最前線、対象外とした作業、確定済みの意思決定、ミッション概要を引き継いでください。各解決内容は対応する子イシューに記載し、親イシューには移行元のパスと移行日を記録したコメントを追加してください。監査用の情報源としてローカルファイルは変更せずに残します。インポートの完了を宣言する前に、すべての意思決定、解決内容、依存関係が反映されていることを確認してください。その後、トラッカーを唯一の稼働中のマップとします。トラッカーを利用できない場合、または船長が承認しない場合は、ローカルマップも重複した取り組みも作成せずに停止してください。

マップは索引であり、保管場所ではありません。各意思決定は必ず1か所、つまりそのチケットに記録します。マップには各解決内容を1行で要約し、リンクを記載します。詳細を繰り返し記載してはいけません。

ドキュメントの言語

マップとチケットの文章には、/oh-my-claudecode:drydock と同じドキュメント言語の契約が適用されます。GLOSSARY.md のフロントマターに documentLanguage があれば、そこから読み取ります（CONTEXT.md だけがあるレガシーなヤードでは、そこから読み取り、2つ目の用語集は作成しません。drydock のレガシー用語集の移行では、ファイル名が変更されます）。ヤードがまだ整備されていない場合は、チャート作成時（W2）に一度だけ言語を尋ね、解決したタグをマップの Notes に記録します。そうすれば、後のローンチ実行でその設定が引き継がれます。パス、ラベル、スラッシュコマンド、navigator:map ラベル、チケットタイプ名（research、loft、grilling、task）、HITL／AFK、blockedBy は固定トークンであり、すべての言語でバイト単位で変更せずに保持します。

マップを作成する

まとまっていないアイデア（またはローンチ時に残った質問）を受けて実行します。チャート作成は1セッションで完了させる作業であり、何も手作業で解決しません。

1. 監査を実行し、指摘事項は先送りします。 /oh-my-claudecode:drydock の --check 監査をレポートのみのモードで実行します。機械的に判定できる範囲は node scripts/shipyard-audit.mjs で、ヒューリスティックな分類は drydock の文章監査で確認します。指摘事項がチャート作成を妨げることはありません（マップが生み出すのは意思決定であり、スロットへの着地ではありません）が、指摘事項はマップの Notes に原文のまま記録します。作業が最終的にデリバリーに入る際、ローンチ時のヤードゲートがその負債を回収します。ヤードがまったく整備されていない場合（GLOSSARY.md も docs/adr/ もない場合）は、/oh-my-claudecode:drydock を一度だけ提案します。船長が断った場合は、トラッカーのみのモードで続行し、堆積物はすべて先送りにします（堆積物を参照）。
2. W1 — 目的地を決める。 Skill ツールを「deep-interview」とともに呼び出し、このマップが何を目指すのか、つまり仕様、意思決定、または変更を明確にします。目的地によってスコープが決まるため、最初に確定します。W1 は船長の署名です。目的地を示し、明確な確認を得てください。 インタビューの支援を受けても船長が目的地を示せない場合、それはエラーではありません。最有力候補を順位付きで提示し、どれに向けてチャートを作成するか、または作業を保留するかを船長に選んでもらいます。
3. フロンティアをマップ化する。 「deep-interview」でさらに掘り下げ、フロンティアラウンドで幅優先に（--frontier）進めます。1つのスレッドを深く掘り下げるのではなく、全体に広げます。各ラウンドでは、前提条件が確定した意思決定のフロンティア全体について問いかけ、回答を受けて再計算し、未決の意思決定と、今すぐ着手できる最初のステップを明らかにします。既存のマップを対象にチャートを作成する場合（残った質問や描き直し）は、チケットを作る前に Out of scope セクションを読みます。対象外と判断された作業が、新しいチケットとして再び持ち込まれることはありません。これによって不明点が何も見つからない場合、つまり目的地までの道筋がすでに明確で、1セッションで完了できるなら、マップは不要です。そこで停止し、/oh-my-claudecode:launch を推奨します。
4. W2 — チャートに署名する。 提案するマップを提示します。目的地、タイプとブロック関係を含む最初のチケット、そして不明点の概要を示します。W2 は船長の署名です。 ここで粒度を誤ると、その後のすべてのセッションが無駄になります。署名を得るまで調整します。
5. マップとチケットを作成する。 マップに navigator:map ラベルを付け、子チケットを作成し、2回目のパスでブロック関係を設定します（チケット同士を参照するには、先に課題 ID が必要です）。チケット化できるほど明確でない内容は、すべて Not yet specified に残します。
6. 調査サブエージェントを起動する。 作成した research チケットごとに、並行して調査を解決するバックグラウンドサブエージェントを起動します（「チケットタイプ」を参照）。チケットからリンクできる場所に調査結果を記録します。
7. セッション終了時の案内を提示して停止します。マップへのリンク、フロンティア上のチケット数、および「次のセッションで /oh-my-claudecode:ask-navigator を実行して、次の意思決定に取り組んでください。」を含めます。

マップに沿って作業する

マップ（リンクまたは番号）を指定して呼び出すか、引数なしで呼び出すと、開いているマップを引き継ぎます。チケットの指定は任意です。指定がない場合は、責任者が選ぶ必要のあるチケットではなく、次のフロンティアチケットに取り組みます。

1. マップを読み込む：低解像度のビューを確認します。すべてのチケット本文を読むことはありません。必要に応じて、チケットの本文全体をズームして確認します。
2. 作業前に担当を割り当てる：並行セッションがそのチケットをスキップできるよう、最初にチケットを責任者に割り当てます。未割り当てのオープンチケットは、未割り当てとして扱います。権限がない、担当者を指定できないなどの理由で割り当てられない場合は、チケットのコメントに担当を記録します。
3. 解決する：「チケットの種類」に従って解決します。必要に応じてズームし、解決に責任者の意見が必要な場合は、Skill ツールを「deep-interview」を指定して呼び出します。
4. 解決内容を記録する：回答をチケットに解決コメントとして投稿し、チケットをクローズします（完了としてクローズします。行き先の範囲外と判断されたチケットは、予定なしとしてクローズします）。そして、マップの課題本文にあるこれまでの決定事項に、次の形式で1行追加します — [<ticket title>](link): <one-line gist>。クローズされたチケットの解決コメントが決定事項の正式な記録場所であり、マップの行はその索引です。
5. フロンティアを進める：回答によって仕様を定められるようになった曖昧な項目をすべて具体化します（未指定から削除し、新しいチケットを作成して、依存関係をつなぎます）。チケットが行き先の範囲外であると回答から判明した場合は、クローズし、後のセッションや別のマップで照合できるよう、概念と理由を記した1行を対象範囲外に残します。決定によって無効になったチケットは更新または削除します。
6. 堆積させる（「堆積」を参照）。
7. チケット1件で停止する。1セッションにつき1件の解決が基本です。これはコンテキストウィンドウの予算であり、ポリシーではありません。セッション終了時のポインターには、直前に解決した内容と現在のフロンティアを記します。一次情報はマップの課題、セッションメモリーは二次情報です。すべてのセッションはマップから状況を把握し、前のセッションのメモリーからは把握しません。

大規模な取り組み — マップはセッションを超えて存続する

作業の見通しを立てた結果、フロンティアにある課題が、複数の独立したスレッドにまたがって決定事項を広げている場合や、行き先を定めても次々と新たな曖昧さが生じる場合など、何度セッションを重ねても短期間では解消できそうにない取り組みが判明したときは、マップ自体をローンチまでの短い通過点ではなく、長期的に存続するものとして扱います。

• 決定事項をまとまりごとに分ける：フロンティアにある独立したスレッドを、それぞれマップの「メモ」に記載するまとまりとして名前を付けます。各まとまりに子チケットを紐付けることで、セッションごとに全体を読み直さなくても、どのセッションからでも該当するスレッドを把握できます。
• マップの課題に集計行を記載する：まとまりごとのオープンチケット数と現在のフロンティアを示す1行を記載し、毎セッション更新します。マップだけを読んだセッションでも、取り組みの進捗を把握できます。
• 1セッションにつき1件のチケットという予算は、セッションを重ねても優先順位に従ってマップのフロンティアに充てる — 基本の進め方は変わらず、変わるのは見通す期間だけです。

長期的に存続するかどうかはマップの性質であり、モードを切り替えるものではありません。同じマップの課題、同じ子チケット、同じルールを使います。曖昧さが解消されたときの締めくくりも変わりません。決定事項をミッションブリーフにまとめ、引き継ぎます。

チケットの種類

すべてのチケットはHITL（本人の言葉で話すキャプテンと一緒に進める）またはAFK（ナビゲーターのみで進める）です。HITL チケットは、対話を通じてのみ解決します。エージェントがキャプテン側の役割を務めることはありません。

種類	モード	解決方法	使用する場面
research	AFK	バックグラウンドサブエージェントが一次資料（公式ドキュメント、ソースコード、仕様）をもとに調査します。調査結果はチケットへのトラッカーコメントとして記録します。回答に成果物が必要な場合は、マージしない一時的なブランチに記録し、チケットからリンクします。恒久的な調査ファイルは作成しません。調査結果はセッション、トラッカーコメント、またはマージしない一時的なブランチに残るため、リポジトリに新たな恒久ファイルは一切追加されません	現在の作業ディレクトリの外にある知識がないと判断できない場合
loft	HITL	Skill ツールを「loft」と指定して呼び出します。一時的な成果物でチケットの問いに答えます。クリック可能なシェル内の純粋なロジックモジュールや、1つのルートの背後にある、構造が異なる UI のバリエーションなどです。キャプテンが反応し、その回答を解決内容に反映します。成果物は loft/<name> ブランチに残します	問いは明確でも、文章だけでは決着せず、説明するのではなく実際に見たりクリックしたりする必要がある場合
grilling	HITL	Skill ツールを「deep-interview」と指定して呼び出し、各ラウンドでキャプテンが判断します	会話そのものが解決となる場合。これがデフォルトです
task	HITL または AFK	可能な範囲ではナビゲーターのみで進め、それ以外の場合はキャプテンに明確なチェックリストを渡します	判断を前に進めるための手作業（サービスへのサインアップ、アクセス権の付与、データを移動して構造を確認できるようにするなど）。目的地を実現するためではなく、判断を前に進めることで価値を発揮します

回答をチケット本文に記載することはありません。解決時に記録します。解決時に作成したアセットはチケットからリンクし、本文に貼り付けません。

知識がドキュメントではなく人物にある research チケットは、その人物に直接尋ねて解決します。許可されたコミュニケーション範囲に従い、その人物の名前を記したトラッカーコメントを1件投稿します。コメントは一読で回答に必要な情報をすべて把握できる内容にし、その人物の返信を一次資料として引用します。ドキュメントを出典とする場合と同じ基準です。事前の接点がない第三者には連絡しません。証拠から名前が特定されていない人物には質問しません。解決記録には回答者と回答場所を記載し、マップのインデックスが言い換えではなく返信を参照するようにします。

research の記録には、このヤードで共通の証拠形式を使います。まず、回答する問いを言い直します。すべての主張に出典をリンクし、最後に未検証セクションを設け、確認できなかったことと、それが重要である理由を記載します。

マップ本文

## 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; deferred drydock --check findings (verbatim); resolved documentLanguage tag; tracker caveats>

## Decisions so far



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

## Not yet specified



## Out of scope



## Mission brief

不確実な状態か、チケットか？ 判断基準は、今すぐ答えられるかどうかではなく、今すぐ問いを正確に述べられるかどうかです。問いがすでに明確なら、阻害要因があってもチケットにします。まだ明確に表現できない場合は、まだ仕様が定まっていない状態です。不確実な状態をチケットサイズに細分化しないでください。1つのパッチから複数のチケットが生まれることも、チケットが生まれないこともあります。スコープ外はスコープを定める行為であり、進行ルート上の一段階ではありません。そこに作業が入るのは明確さではなくスコープによるもので、目的地が再設定された場合にのみ戻ってきます。

堆積物

決定が確定すると、その内容はただちに造船所の記録に残ります。これは、launch の Phase 1 で使われるのと同じ記録先です。

• 決定によって確定または明確化された用語 → GLOSSARY.md の用語集（定義、境界、解消された曖昧さを含む1項目）
• ADR の条件を満たす決定（覆すのが難しく、背景を知らなければ意外で、実質的なトレードオフがある）→ docs/adr/NNNN-<slug>.md
• ビジネスルールまたは背景情報 → docs/business/（ビジネス上の質問1件につき記事1つ）

レガシー造船所（CONTEXT.md のみ）：造船所に、レガシー用語集として認識できる CONTEXT.md だけがあり、GLOSSARY.md がない場合は、堆積物を書き込む前に drydock を実行して、用語集の正本を GLOSSARY.md に移行してください。レガシーファイルと並べて新しい GLOSSARY.md を作成してはいけません。正本が分裂してしまいます。drydock によるレガシー用語集の移行が完了すると、用語集への書き込み先は自動的に GLOSSARY.md になります。または、この堆積物の反映をマップの Notes に延期してください（下記参照）。

造船所が未整備の場合（チャート作成時に船長が drydock を見送った場合）、見送るのではなく、延期してください。保留中の反映を1件につき1行で、マップの Notes に Deferred sediment という見出しの下へ記録してください。後続の /oh-my-claudecode:launch の実行では、造船所ゲートが基盤となる領域を必須とし、採用済みのオプション領域のみを監査します。採用されていないオプション領域が指摘事項になることはありません。延期した行によって、launch の実行でどの初回利用トリガーを発動し、何を反映すべきかが明確になります。

完了 — 構築せず、引き継ぐ

未解決のチケットがなく、Not yet specified が空になった時点で、マップは完成です。その後、次の手順を実行します。

1. Decisions so far を、目的、スコープの境界、対象外事項を含むミッションブリーフにまとめ、マップの課題本文にある Mission brief の下へ記載します。引き継ぎで渡すポインターは1つ、つまりマップの課題そのものです。ブリーフファイルは作成しません。
2. 次のように推奨します。「道は開けました。マップの課題をミッションブリーフとして /oh-my-claudecode:launch を実行してください。ブリーフへのポインターはマップの課題本文にあります。」マップは取り組みの航海日誌として残し、それ以降の確認はすべて launch の造船所ゲートが担います。
3. 既定の開始地点は launch の Phase 1 です（記録はすでに半分ほど埋まっており、残りの確認はすぐに終わります）。すでに決定事項が仕様書のようにまとまっている場合に限り、仕様書を作成して Phase 2 から launch を開始し、仕様書トラッカーの課題参照（親となる仕様書課題の番号またはリンク）を引き継ぎます。

スコープと対象外事項

• デーモンもモードも常時稼働する動作もランタイム状態機械もありません。マップは通常のトラッカー課題であり、リポジトリファイルには何も書き込みません。
• 霧のように不明確なまま届いた依頼は、振り分けを港に委ねます。/oh-my-claudecode:harbor から引き継がれた曖昧な課題も、あらゆる未整理のアイデアと同様にチャート化し、元のスレッドと署名済みの決定リンクがあればそれを資料として扱います。
• Team のライフサイクル、タスクのステータス、ランタイム状態は変更しません。デリバリーチケットも作成しません。垂直スライスの構築チケットは launch の C3 に属し、ナビゲーターは霧のような未整理の内容を事前に分割してチケット化してはいけません。
• 決定を記録する以上のことは実行しません。唯一の例外は task チケットで、決定を進めるために必要なことだけを行います。
• マップの Decisions-so-far は索引です。決定が記録される場所は、そのチケットの1か所だけです。

完了の定義

チャート作成セッションは、船長が署名したマップと、発行済みの調査チケットをもって終了します。作業セッションは、解決事項がちょうど1件記録され、フロンティアが進み、セッション終了時のポインターが出力された時点で終了します。道が開け、ミッションブリーフが船長に渡され、/oh-my-claudecode:launch が推奨された時点で、この取り組みは終了します。ナビゲーターが船長に代わって行ったすべての決定について、記録先を示すポインター1つで確認できる状態にします。