Map-First Planning

The planning move for a problem that is too big for one agent session and wrapped in fog — the destination is roughly known but the route to it isn't visible yet. Instead of trying to grill and spec the whole thing in one sitting (and blowing past the agent's "smart zone" or context window), you chart the effort as a persisted, shared map of session-sized tickets on the repo's issue tracker and resolve them one at a time until the way is clear, then convert the finished map into a spec in the normal way. The source's slogan is "finding the way, not charging at the destination" and its skill's section header is literally "Plan, don't do."

What distinguishes this from an ordinary Agent Task Graph is what gets decomposed: not the build work, but the unknowns — the open decisions and investigations that stand between a loose idea and a plan you can execute. Each is scoped to fit one agent session, so you close a session and open the next ticket without the anxiety of hand-managing context across a marathon planning run. Because the map lives in the issue tracker (GitHub issues + sub-issues with blocking edges), it is durable and collaborative — shareable across a team, resumable across sessions — where a single long grilling conversation is neither. The concrete instance in the source is Wayfinder, positioned in its own repo as a situational on-ramp that replaces grill-with-docs when the plan is large and foggy — not the default entry to every flow.

Claims

When a plan is too big for one agent session and its route is uncertain, decompose the unknowns into session-sized tickets on a persisted shared map and resolve them in dependency order before you spec. best practice — context: large, high-uncertainty efforts that would overflow one agent's smart zone or context window; for a plan that fits one session this is overhead, and grill-then-spec is enough. The map earns its keep exactly when the route isn't visible up front.
Name the destination first — it is "the first act of charting," and it shapes every ticket. principle — durable: a plan's decomposition is constrained by its target, so fixing the target before enumerating steps is what keeps the tickets coherent; holds independent of tool or domain (the source calls the map domain-agnostic — engineering, course content, whatever fits).
Plan, don't do: keep the map-building phase separate from execution so the agent charts the route instead of charging at the destination. principle — durable: the failure it prevents is an agent that rushes to build before the unknowns are resolved; this is Step Isolation applied to the plan/execute boundary.
Persist the map in the issue tracker so it is durable, resumable across sessions, and collaborative — not trapped in one conversation. best practice — context: efforts that span multiple sessions or people; contingent on a tracker with sub-issues and blocking edges (GitHub in the source). A throwaway single-session plan does not need the persistence.
The author's own end-to-end tutorial starts at grill-with-docs and never reaches for Wayfinder — corroborating the situational-on-ramp positioning from the negative side. observation — a later video explicitly scoped to "the main flow… not the new stuff" walks the five steps with wayfinder visible only in the /-command palette. The curriculum confirms what the commit message ("settle wayfinder as a situational on-ramp, not the main entry flow") asserted: this is the tool for foggy oversized work, not the default door.
The map, once complete, converts into a spec in the regular way — map-first planning is a pre-spec stage, not a replacement for the spec. observation — it sits ahead of Spec-Driven Development's /to-spec, feeding it a resolved plan rather than a foggy idea.

Agent Task Graph — the substrate this rides on: blocks/blockedBy edges with per-ticket ownership. Map-first planning is the specialization that decomposes unknowns (not build work) and scopes each node to one session; Wayfinder is a third concrete instance of the task graph.
Resolution-Typed Tasks — how each ticket on the map is typed (research / prototype / grilling / task; HITL vs AFK), which routes the work that resolves it.
Step Isolation — "plan, don't do" is the same hide-the-future discipline: keep the agent on the current unknown instead of sprinting to the destination.
Spec-Driven Development — the downstream stage; a completed map becomes the spec.
Fidelity-Raising Prototype — one resolution mode for a foggy node: make a cheap artifact to react to when the unknown is "how should it look / behave."
Shared Review Surface — the map-in-the-tracker is collaborative for the same reason: a shared, persisted artifact both people (and agents) read and write.
Context Smart Zone — the limit this page keeps invoking ("too big for one agent session," "blowing past the agent's smart zone") given a page of its own: what the zone is, why it degrades before the window fills, and why it is the unit that sizes every ticket on the map.
Distillate: Skills v1.1: Wayfinder, the SDLC flow, and naming the artifact right
Distillate: The whole flow, end-to-end: the smart zone is the unit of work — the same author's main-flow tutorial, which starts at grill-with-docs and leaves Wayfinder out of the flow entirely.
Distillate: You're the Problem, Not Claude — Six Fixes to 10x Output — corroborates the plan-before-execute discipline from the "gardener not sculptor" angle: create a plan and set goals first, then let AI execute and verify, rather than hand-prompting toward the output.

Map-First Planning

Claims

Related

Linked from