Ask Navigator

Ask Navigator

Ask-navigator is the shipyard's navigator: it takes an effort wrapped in fog — the way from here to the destination isn't visible yet — and charts it as a map of decision tickets on the repo's issue tracker, then works the frontier one ticket per session until the route is clear. It produces decisions, never deliverables: when the way is clear it hands off, it doesn't build. Delivery belongs to /oh-my-claudecode:launch.

The role contract. The captain (the human) signs the destination (W1) and the chart (W2); the navigator drafts everything else and never answers a question that belongs to the captain — a grilling session in which the agent answers its own questions has broken the role, not just the process. Facts are the navigator's job; decisions are the captain's.

Fog test. An effort has fog when either answer is no:

1. Q1 — Can the destination be stated in one sentence: the spec, decision, or change this effort is finding its way to?
2. Q2 — Can the first three decisions be stated precisely right now, even though none of them can be answered yet?

Both yes → no map is needed; run /oh-my-claudecode:launch (its fog gate sends efforts here only when an answer is no). Either no → chart first. ask-navigator is also reachable directly: invoke it with a loose idea, with residual questions handed over by launch's fog gate, or with no argument to continue the open map.

Map home

The map is a single issue labelled navigator:map on the repo's issue tracker; its decision tickets are child issues of the map. The tracker should have been recorded by /oh-my-claudecode:drydock; if none was recorded, ask once (GitHub / GitLab / local markdown) and remember the answer inside the map's Notes.

• Tracker-backed (GitHub, GitLab, or recorded tracker): one map issue, child issues per ticket, native blocking/sub-issue relationships. Concurrent sessions and the tracker's own UI render the frontier — the map lives where humans already look. Create the navigator:map label if the tracker doesn't have it yet; ticket types live in the ticket body, not in labels.
• Local markdown fallback: .omc/wayfinder/<map-slug>/map.md plus decisions/NN-<slug>.md, one file per ticket, numbered in dependency order. Local mode has no concurrent-claim guarantee: it is single-driver by convention, stated once in the map's Notes.

The map is an index, not a store: a decision lives in exactly one place — its ticket. The map gists each resolution in one line and links; it never restates the detail.

Document language

Map and ticket prose follow the same document-language contract as /oh-my-claudecode:drydock: read documentLanguage from CONTEXT.md frontmatter when present; if the yard is not laid, ask the language question once during charting (W2) and record the resolved tag in the map's Notes so the later launch run inherits it. Paths, labels, slash commands, the navigator:map label, ticket-type names (research, loft, grilling, task), HITL/AFK, and blockedBy are stable tokens and stay byte-for-byte stable in every language.

Chart the map

Invoked with a loose idea (or launch's residual questions). Charting is one session's work; it hand-resolves nothing.

1. Run the audit, defer the findings. Run the /oh-my-claudecode:drydock --check audit in report-only mode — the mechanical subset via node scripts/shipyard-audit.mjs, the heuristic classes via the drydock prose audit: findings never block charting (a map produces decisions, not slot landings), but they are recorded verbatim in the map's Notes — launch's yard gate will collect that debt when the effort finally enters delivery. If the yard is not laid at all (no CONTEXT.md, no docs/adr/), offer /oh-my-claudecode:drydock once; if the captain declines, proceed in tracker-only mode and defer all sediment (see Sediment).
2. W1 — name the destination. Call the Skill tool with "deep-interview" and pin down what this map is finding its way to: the spec, decision, or change. The destination fixes the scope, so it is settled first. W1 is a captain signature: present the destination statement and get explicit confirmation. If the captain cannot state a destination even with the interview's help, that is not an error — present the best candidates ranked and let the captain pick one to chart toward or park the effort.
3. Map the frontier. Grill again with "deep-interview", breadth-first with frontier rounds (--frontier): fan out across the whole space rather than deep on any one thread — each round asks the whole frontier of decisions whose prerequisites are settled, then recomputes from the answers — surfacing the open decisions and the first steps takeable now. When charting against an existing map (residual questions or a redraw), read its Out of scope section before ticketing — ruled-out work never re-enters as a fresh ticket. If this surfaces no fog — the way to the destination is already clear and the journey fits one session — no map is needed: stop and recommend /oh-my-claudecode:launch.
4. W2 — sign the chart. Present the proposed map: destination, initial tickets with types and blocking edges, and the fog sketch. W2 is a captain signature: granularity wrong here wastes every later session. Iterate until signed.
5. Create the map and tickets. Label the map navigator:map; create child tickets; wire blocking edges in a second pass (issues need ids before they can reference each other). Everything not yet sharp enough to ticket stays in Not yet specified.
6. Fire the research subagents. For each research ticket just created, spawn a background subagent to resolve it in parallel (see Ticket types), capturing findings where the ticket can link them.
7. Stop with the session-close pointer: the map link, how many tickets are on the frontier, and "next session, run /oh-my-claudecode:ask-navigator to work the next decision."

Work through the map

Invoked with a map (link or number) or with no argument (pick up the open map). A ticket is optional: without one, take the next frontier ticket, not one the captain must choose.

1. Load the map: the low-res view, never every ticket body. Zoom into a ticket's full body on demand.
2. Claim before work: assign the ticket to the captain (tracker) or set Claimed-by (local) first, so concurrent sessions skip it. An open, unclaimed ticket is unclaimed. If assignment isn't possible (permissions, no handle), record the claim in a ticket comment instead.
3. Resolve it according to its type (see Ticket types). Zoom as needed; call the Skill tool with "deep-interview" whenever the resolution needs the captain's input.
4. Record the resolution: post the answer as a resolution comment/section, close the ticket (as completed; a ticket ruled beyond the destination closes as not planned), and append one line to the map's Decisions so far — [<ticket title>](link): <one-line gist>.
5. Advance the frontier: graduate any fog the answer has made specifiable (remove it from Not yet specified, create the new tickets, wire edges); if the answer reveals a ticket sits beyond the destination, close it and leave one line in Out of scope carrying the concept and the reason (so a later session or a later map can match it); update or delete tickets the decision invalidated.
6. Sediment (see Sediment).
7. Stop after one ticket. One resolution per session is the cadence — it is the context-window budget, not a policy. The session-close pointer names what just resolved and what is now on the frontier. The map issue is the primary source, session memory secondary — every session re-orients from the map, never from the previous session's memory.

Large efforts — the map outlives the session

When charting reveals an effort whose frontier no number of sessions is likely to clear quickly — decisions fanning out across several independent threads, a destination that keeps opening new fog — the map itself becomes long-lived rather than a short stop on the way to launch:

• Decisions group into vessels: independent threads of the frontier are named as vessels in the map's Notes, each carrying its child tickets, so any session can orient to one thread without re-reading the whole space.
• The map issue carries a census line: one line stating the open-ticket count per vessel and what the current frontier is, refreshed every session — a session that reads only the map knows where the effort stands.
• The one-ticket-per-session budget is spent on the map's frontier in priority order across any number of sessions — the cadence never changes; only the horizon does.

Long-lived is a property of the map, not a mode switch: the same map issue, the same child tickets, the same rules. When the fog finally clears, the exit is unchanged — collapse the decisions into the mission brief and hand off.