ask-navigator

Ask Navigator

Ask-navigator 是 shipyard 的导航员：它接手一项尚处迷雾中的工作——从这里到目的地的路径尚不可见——并将其绘制成仓库议题跟踪器上的决策工单地图，然后每次会话处理一张工单，逐步探索前沿，直到路线清晰。它产出的是决策，而非交付物：路线清晰后，它会交接，而不是动手构建。交付工作属于 /oh-my-claudecode:launch。

角色约定。 船长（人类）确认目的地（W1）和航图（W2）；导航员起草其他所有内容，并且绝不回答属于船长的问题——如果 Agent 在盘问环节回答了自己的问题，那就是角色失守，而不仅仅是流程出错。事实由导航员负责；决策由船长负责。

迷雾测试。 如果以下任一问题的答案是否，则这项工作处于迷雾中：

1. Q1 — 能否用一句话说明目的地：这项工作要找到通往何处的规格说明、决策或变更？
2. Q2 — 即使现在还无法回答，也能否准确说明最先要做出的三个决策？

两项都是 → 无需绘制地图；运行 /oh-my-claudecode:launch（其迷雾检查只会在答案为否时将工作交到这里）。任一项为否 → 先绘制地图。也可以直接调用 ask-navigator：传入一个模糊的想法、传入 /oh-my-claudecode:launch 的迷雾检查移交的遗留问题，或不带参数以继续现有地图。

地图位置

地图是仓库议题跟踪器上的单个议题，带有 navigator:map 标签；其决策工单是该地图议题的子议题。跟踪器应已由 /oh-my-claudecode:drydock 记录；如果没有记录，请询问一次，并将答案记在地图的 Notes 中。

跟踪器是唯一的地图载体——没有本地回退方案：一个地图议题、每张工单一个子议题，并使用原生的阻塞／子议题关系。并发会话和跟踪器自身的界面会呈现当前前沿——地图就保存在人们平时查看的位置。将地图写入本地文件，会让决策困在之后的会话、船长和 launch 都找不到的地方；不要回退到本地文件。如果无法访问跟踪器，请停止并报告阻塞问题。如果跟踪器还没有 navigator:map 标签，请创建它；工单类型应写在工单正文中，而不是标签中。

现有本地地图的一次性迁移： 在不带参数继续时，如果未找到跟踪器地图，但 .omc/wayfinder/<slug>/map.md 存在，则将其视为导入来源——绝不要另建地图，也不要将本地副本继续用作实时后端。读取该地图及其 decisions/ 条目，识别已配置的跟踪器，并请船长确认导入。获得确认后，创建一个 navigator:map 父议题，为每张决策工单创建一个子议题，建立原生的子议题关系和阻塞关系，并保留当前前沿、已排除的工作、已确定的决策和任务简述。将每项决议写入对应的子议题，并在父议题中添加评论，记录来源路径和导入日期。保持本地文件不变，作为审计来源；在宣布导入完成前，确认每项决策、决议和依赖关系都已体现。此后，跟踪器将成为唯一的实时地图。如果跟踪器不可用，或船长拒绝导入，请停止，不要创建本地地图，也不要创建重复的工作项。

地图是索引，而非存储：一项决策只存在于一个位置——它的工单中。地图用一行概述每项决议并附上链接；绝不复述详细内容。

文档语言

地图和工单中的正文遵循与 /oh-my-claudecode:drydock 相同的文档语言约定：如果 GLOSSARY.md 的 frontmatter 中存在 documentLanguage，则读取该值（旧版 yard 如果只有 CONTEXT.md，则从中读取，且不会再创建第二份 glossary；drydock 的旧版 glossary 迁移会将其重命名）；如果 yard 尚未铺设，则在制图期间（W2）询问一次语言问题，并将确定的标签记录在地图的 Notes 中，以便后续 launch 运行继承。路径、标签、斜杠命令、navigator:map 标签、工单类型名称（research、loft、grilling、task）、HITL/AFK 和 blockedBy 都是稳定令牌，在任何语言中都必须逐字节保持不变。

绘制地图

使用一个宽泛的想法（或 launch 遗留的问题）调用。绘图是单次会话的工作；不会手动解决任何问题。

1. 运行审计，暂缓处理发现项。 以仅报告模式运行 /oh-my-claudecode:drydock 的 --check 审计——通过 node scripts/shipyard-audit.mjs 检查机械性子集，通过 drydock 正文审计检查启发式类别：发现项绝不会阻止绘图（地图用于作出决策，而不是停靠船只），但会原文记录在地图的 Notes 中——当这项工作最终进入交付阶段时，launch 的 yard 门禁会处理这笔欠账。如果 yard 尚未铺设（没有 GLOSSARY.md、没有 docs/adr/），则仅一次提供 /oh-my-claudecode:drydock；如果 captain 拒绝，则以仅跟踪器模式继续，并暂缓处理所有沉积物（参见“沉积物”）。
2. W1 — 确定目的地。 使用“deep-interview”调用 Skill 工具，明确这张地图要通往什么：规范、决策或变更。目的地决定范围，因此要先确定。W1 是 captain 的签署：展示目的地说明，并获得明确确认。 如果 captain 即使在访谈协助下也无法说明目的地，这并非错误——按优先级展示最佳候选项，让 captain 选一个作为绘图目标，或暂缓这项工作。
3. 绘制前沿。 使用“deep-interview”再次深入访谈，采用广度优先的前沿轮次（--frontier）：覆盖整个空间，而非深入某一条线索——每一轮都询问前置条件已确定的所有决策，然后根据答案重新计算，从而揭示尚未解决的决策和当前可采取的第一步。针对现有地图进行绘图（处理遗留问题或重绘）时，在创建工单前先阅读其 Out of scope 部分——已排除的工作绝不会以新工单的形式重新进入。如果没有发现迷雾——通往目的地的路径已经清晰，且整个过程只需一次会话——则无需地图：停止并建议使用 /oh-my-claudecode:launch。
4. W2 — 签署图表。 展示拟定的地图：目的地、带有类型和阻塞边的初始工单，以及迷雾草图。W2 是 captain 的签署：此处的粒度若不合适，会浪费之后的每一次会话。反复调整，直到签署通过。
5. 创建地图和工单。 为地图添加 navigator:map 标签；创建子工单；在第二轮中连线设置阻塞边（问题必须先有 ID，才能相互引用）。所有尚未明确到足以创建工单的内容，都放在 Not yet specified 中。
6. 启动 research 子代理。 对刚创建的每个 research 工单，启动后台子代理并行解决（参见“工单类型”），并将发现记录在工单可链接的位置。
7. 停止并给出会话结束指引：地图链接、前沿上有多少工单，以及“下一次会话，运行 /oh-my-claudecode:ask-navigator 处理下一个决策。”

推进地图

通过地图（链接或编号）调用；也可不带参数调用（接续当前打开的地图）。工单是可选的：若未指定工单，就处理下一个前沿工单，而不是必须由负责人选择的工单。

1. 加载地图：只查看低分辨率视图，绝不加载所有工单正文。需要时再放大查看某个工单的完整正文。
2. 开始前先认领：先将工单分配给负责人，这样并行会话就会跳过该工单。处于打开状态且尚未认领的工单，就是未认领工单。如果无法分配（权限问题或没有负责人账号），则在工单评论中记录认领信息。
3. 解决工单：根据工单类型处理（参见 Ticket types）。按需放大查看；只要解决过程需要负责人提供意见，就调用 Skill 工具并使用 "deep-interview"。
4. 记录解决结果：在工单上发布一条解决结果评论，关闭工单（标记为已完成；若裁定该工单超出目标范围，则关闭时标记为不计划处理），并在地图议题正文的 Decisions so far 中追加一行：[<ticket title>](link): <one-line gist>。已关闭工单的解决结果评论是决策的唯一归档处；地图中的那一行是指向该评论的索引。
5. 推进前沿：将答案已足以明确的模糊事项纳入范围（从 Not yet specified 中移除，创建新工单并连接依赖关系）；如果答案表明某工单超出目标范围，则关闭该工单，并在 Out of scope 中留下一行，写明相关概念和原因（方便后续会话或地图识别）；更新或删除因该决策而失效的工单。
6. 沉淀（参见 Sediment）。
7. **每次只处理一个工单。**每个会话解决一个问题，这是上下文窗口的预算限制，而非政策要求。会话结束指针会注明刚刚解决的问题以及当前前沿。地图议题是首要信息源，会话记忆仅作辅助——每个会话都要重新根据地图确定方向，绝不依赖上一个会话的记忆。

大型工作——地图的生命周期长于会话

如果绘制地图后发现，某项工作的前沿需要多个会话才能逐步清理——决策分散在几条相互独立的线程中，或目标不断衍生出新的模糊事项——那么地图本身就会变为长期地图，而非通往发布的一段短暂停留：

• 决策归入不同容器：在地图的 Notes 中，将前沿的独立线程命名为不同容器，并为每个容器关联其子工单，使任何会话都能专注于一条线程，无需重新阅读整个范围。
• 地图议题记录清单行：用一行说明每个容器中的未关闭工单数量以及当前前沿，并在每个会话中刷新——只查看地图的会话也能了解工作的进展。
• 每个会话处理一个工单的预算，按优先级用于地图前沿，可跨越任意数量的会话——推进节奏不变，只是时间跨度变长。

长期性是地图的属性，而不是模式切换：地图议题、子工单和规则都保持不变。模糊事项最终厘清后，退出方式也不变——将决策归纳到任务简报中并交接。

工单类型

每个工单都是 HITL（与代表自己发言的船长协作完成）或 AFK（仅由导航员驱动）。HITL 工单只能通过实时交流解决；Agent 绝不代替船长一方发言。

类型	模式	解决方式	适用场景
research	AFK	后台子 Agent：依据一手来源（官方文档、源代码、规范）进行调查；将发现记录为工单上的追踪器评论；如果需要产物来回答问题，则记录在永不合并的临时分支上，并从工单中链接该分支。不会创建永久研究文件：发现仅存在于会话、追踪器评论或临时分支（永不合并）中，因此仓库不会增加任何新的永久文件	决策取决于当前工作目录之外的知识
loft	HITL	调用 Skill 工具并传入 "loft"：用临时产物回答工单的问题——可以是可点击外壳中的纯逻辑模块，也可以是同一路由下结构不同的 UI 变体；船长给出反馈，答案融入解决方案，产物保留在 loft/<name> 分支上	问题很明确，但仅靠文字无法敲定——需要亲眼看见或实际点击，而非口头描述
grilling	HITL	调用 Skill 工具并传入 "deep-interview"；每一轮都由船长决定	通过对话来解决——默认情形
task	HITL 或 AFK	能由导航员独立完成的部分由其驱动；否则向船长提供精确的检查清单	能推动决策的手动工作（注册服务、配置访问权限、移动数据以便查看其结构）——其价值在于推动决策，而非交付最终目标

答案永远不会写入工单正文；而是在解决时记录。解决过程中创建的资源会从工单中链接，而非直接粘贴进去。

如果某个 research 工单所需知识存在于某个人而非文档中，就直接向此人提问来解决：根据获准的沟通范围，在一条追踪器评论中点名此人，并提供其一次阅读即可作答所需的全部信息；将其回复作为一手来源引用——标准与文档来源相同。不得冷联系第三方；证据中未提及的人不会收到问题。解决记录会注明回答者及回答位置，因此地图索引指向回复，而非转述内容。

research 记录采用 yard 的统一证据格式：开头重述其要回答的问题，每项论断都链接到来源，结尾设有 未验证 部分，说明哪些内容未能确认以及原因。

地图正文

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

迷雾还是工单？ 判断标准是你现在能否准确表述问题，而不是现在能否回答问题。只要问题已经明确，即使受阻，也应创建工单。无法如此明确地表述时，就标记为尚未明确；不要把迷雾预先切分成工单大小的片段：一个补丁可能发展成多个工单，也可能一个都没有。超出范围是一项范围界定行为，而非路线上的一个步骤：让工作归入此处的是范围，而非明确程度；只有重新绘制目的地后，它才会返回。

沉淀

决议一经敲定，就会立即进入船厂的文档记录——使用与 launch Phase 1 相同的位置：

• 敲定或明确的术语 → GLOSSARY.md 词汇表（一个条目：定义、边界、消除的歧义）
• 符合 ADR 标准的决策（难以撤销、缺少背景时令人意外、涉及真实取舍）→ docs/adr/NNNN-<slug>.md
• 业务规则或背景事实 → docs/business/（每个业务问题对应一篇文章）

旧船厂（仅有 CONTEXT.md）：如果船厂只有可识别的旧版词汇表 CONTEXT.md，没有 GLOSSARY.md，请先运行 drydock，将词汇表的权威来源迁移到 GLOSSARY.md，再写入沉淀。不要在旧文件旁新建 GLOSSARY.md；这会导致权威来源分裂。drydock 的旧版词汇表迁移完成后，词汇表写入将自动指向 GLOSSARY.md。或者，也可以将这项沉淀记入地图的 Notes（见下文），暂缓写入。

如果船厂尚未整备（船长在绘制地图时拒绝了 drydock），应暂缓，而非跳过：在地图的 Notes 下设立 Deferred sediment 标题，并将每项待写入的沉淀各记录为一行。之后运行 /oh-my-claudecode:launch 时，船厂门禁会检查基础面，并且只审核已采用的可选内容面——未采用的可选内容面不会成为问题；这些延后记录会明确告诉 launch 运行应触发哪项首次使用条件，以及要将内容写入何处。

收尾 — 交接，而非构建

没有未解决的票据，且 Not yet specified 为空时，地图即告完成。然后：

1. 将 Decisions so far 汇总为一份任务简报——目标、范围边界、非目标——并写入地图议题正文中的 Mission brief 部分。交接只传递一个指针，即地图议题本身；不创建简报文件。
2. 建议：“道路已畅通。将地图议题作为任务简报运行 /oh-my-claudecode:launch——简报指针位于地图议题正文中。”地图继续作为本次工作的日志簿；从此之后，所有检查均由 launch 的船厂门禁负责。
3. 默认从 launch Phase 1 开始（文档记录已基本完成；快速清理剩余事项即可）。只有当现有决策已足以构成规格说明时，才可以起草规格说明并从 Phase 2 进入 launch，同时附上规格说明跟踪议题的引用（父级规格说明议题编号或链接）。

范围与非目标

• 没有守护进程、模式、常驻行为或运行时状态机：地图只是普通的跟踪器议题——不会向仓库文件写入任何内容。
• 雾状的传入请求由港口负责分流：由 /oh-my-claudecode:harbor 移交的模糊议题，绘制时与任何松散想法无异；原始讨论串和任何已签署的决策链接都是可用材料。
• 绝不更改 Team 生命周期、任务状态或运行时状态；绝不发布交付票据——纵向切片构建票据属于 launch 的 C3，领航员不得预先将雾状需求拆分成这类票据。
• 绝不执行决策，只记录决策。唯一例外是 task 票据，它只负责解除决策的阻碍。
• 地图中的 Decisions-so-far 只是索引；每项决策只存放于一个位置，即其票据。

完成定义

绘制地图的会话以船长签署地图并启动研究票据为结束。工作会话以恰好记录一项决议、推进待决事项，并发出会话收尾指针为结束。当道路已畅通、任务简报已交到船长手中，并建议运行 /oh-my-claudecode:launch 时，本次工作即告结束——领航员代表船长所作的每项决策，都能通过一个指针找到其记录位置。