Wayfinder

Wayfinder

Wayfinder turns a vague, multi-session task into a plan organized around the destination — the end state you are navigating toward — rather than a flat list of steps. It exists for work that cannot be scoped and finished inside a single session: large migrations, cross-cutting features, or ambiguous initiatives where the first hour is spent figuring out what "done" even means.

When to Use

• The task is too large, ambiguous, or long-running to complete in one session
• You need a shared map that multiple sessions, agents, or people can navigate from
• Early exploration keeps surfacing tangents that are real but not part of this pass
• You need a plan that survives a context reset without losing track of what was deliberately skipped

When NOT to Use

Wayfinder produces the destination-centric map; to-issues slices an approved plan into dependency-aware tickets; deep-research gathers evidence to inform a decision. Chain them in that order when a large initiative needs all three.

Workflow

1. Name the destination

Write the end state in outcome language, not task language:

Destination: [what the world looks like when this is done]
Not the destination: [adjacent goals this pass explicitly does not include]

A destination is a state, not a checklist. "Auth is fully migrated to the new session store" is a destination. "Update 12 files" is not.

2. Breadth-first triage

Before going deep on any single area, sweep the whole territory once:

1. List every area that plausibly touches the destination
2. For each area, spend just enough time to classify it — do not solve anything yet
3. Sort each area into one of three buckets:
   • In scope — required to reach the destination this pass
   • Fog — unknown enough that it needs its own investigation before it can be scoped
   • Deferred / out of scope — real, but explicitly not part of this destination

Only after the full breadth-first pass is complete should any area get depth-first investigation. Going deep on the first area you find is how large plans quietly narrow to whatever was convenient to start with.

3. Incinerate researchable Fog immediately

If a Fog item is blocking progress and can be resolved by investigation alone, convert it into an independent research ticket immediately instead of parking it for later.

Convert a Fog item into a research ticket only when all of these are true:

• the blocker can be answered from code, docs, prior artifacts, or web research without another live user decision first
• the question is concrete enough to investigate independently
• the work is bounded to research, not implementation
• the answer will change whether the area becomes In Scope, stays Fog, or moves to Deferred

Ticket shape:

Question: [what must be answered]
Why blocked: [what this uncertainty is preventing]
Suggested sources: [code paths, docs, tickets, web docs]
Definition of done: [what finding would let the plan move]

Required subagent report-back format:

• Question — restate the ticket in one line
• Answer — best current conclusion
• Source / evidence — concrete files, docs, or links
• Confidence — high | medium | low
• Remaining uncertainty — only what still needs a human decision or extra evidence

Parallelism rule:

• Dispatch up to 3 independent research tickets in parallel
• If the session has exactly 1 research ticket and it looks small enough for a short inline investigation, resolve it inline instead of paying subagent overhead
• If there are 2+ independent tickets, or the single ticket will take enough digging that it would stall other work, dispatch subagents immediately
• As results return, fold them back into the Fog / In Scope / Deferred map before continuing

4. Write the Deferred section explicitly

Do not let out-of-scope discoveries disappear. Record them so a future pass — or a different session — can pick them up without rediscovering them:

## Deferred

- [item] — why it's out of scope for this destination, and what would trigger picking it up

An item that is merely unaddressed is not the same as an item that was deliberately deferred. Only the second kind belongs here.

5. Confirmation gate

Before any implementation starts, present the destination, the in-scope/fog/deferred split, and ask for explicit confirmation. Do not begin execution on an unconfirmed map — fog items in particular need a decision (investigate now vs. defer) before they can be scoped into or out of the plan.

6. Self-grill the plan

Before treating the plan as final, challenge it once from an adversarial angle:

• What would make this destination wrong or premature?
• Which "in scope" item is actually fog wearing a confident label?
• What Deferred item is likely to block the destination anyway?

Fold the answers back into the plan rather than leaving them as a detached appendix.

Output Template

## Wayfinder Plan: [Destination Name]

**Destination**: [end state, in outcome language]
**Not the destination**: [adjacent goals excluded from this pass]

### In Scope
- [area] — [why it's required for the destination]

### Fog
- [area] — [what's unknown, what investigation would resolve it]

### Research Tickets
- [question] — [owner: inline or subagent], [what answer would unblock]

### Deferred
- [item] — [why excluded now, what would trigger revisiting it]

### Confirmation
- [ ] Destination confirmed
- [ ] Fog items have an investigate-now-vs-defer decision
- [ ] Blocking Fog items were converted into research tickets or deliberately deferred
- [ ] Ready to move to ticketing (`to-issues`) or direct execution

Common Rationalizations

Red Flags

• No explicit Deferred section — tangents were either done anyway or silently dropped
• Implementation started before the destination and fog/in-scope split were confirmed
• "Fog" areas that were never actually investigated before being called in-scope
• The plan reads as a flat task list instead of being organized around the destination

Verification

• The destination is written as an outcome, not a task list
• Every area went through breadth-first triage before any depth-first work began
• Researchable blocking Fog was converted into bounded tickets instead of being parked vaguely
• Deferred items are recorded with a reason and a trigger for revisiting
• The user confirmed the plan before implementation started

See Also

• to-issues — slice an approved plan into dependency-aware tickets
• deep-research — gather evidence to resolve fog before scoping it
• fleet-parallel — dispatch multiple independent research tickets in parallel when the map has more than one blocker
• plan-mode-mastery — single-session plan.md workflow for smaller-scoped work