A plan document is the wrong artifact for AI work that spans multiple sessions. I learned this the expensive way: the reasoning that produced a plan lives in the conversation, and the conversation dies when the session ends. The next session reads your beautiful markdown plan and confidently rebuilds an assumption you already killed two days ago. The Wayfinder skill, from Matt Pocock's engineering skills pack, is the first tool I've seen that treats this as the core problem instead of a footnote.
I run Claude Code daily across a Laravel monorepo, client builds, and content pipelines, and almost everything worth doing is bigger than one session. Here is how Wayfinder actually works, what my own multi-session workflow taught me before I found it, and the specific cases where reaching for it is a mistake.
What a multi-session project taught me before Wayfinder existed
Last month I rewrote 84 blog posts on this site across seven batches and more than a dozen Claude Code sessions. The thing that kept it from collapsing was not a plan document. It was a dumb little file called REWRITE-STATUS.json — a manifest listing every post ID with a DONE or PENDING flag, updated by a mark_done.php script after each batch was applied and verified.
Any fresh session could read that manifest in two seconds and know exactly where the project stood. No summarizing the previous conversation, no re-deriving state from git history. The manifest was the project's memory; the sessions were disposable.
But a manifest only tracks work. It cannot tell a fresh session why batch three switched link formats, or why we stopped trusting a category of source. Those were decisions, argued out in conversations that no longer exist. That gap — durable decisions, not just durable status — is precisely what Wayfinder fills.
What the Wayfinder skill actually does
Wayfinder charts a large effort as a map of decision tickets on your repo's issue tracker, then resolves them one at a time across as many sessions as it takes. Two ideas make it work:
The ticket is a question, not a task. A Wayfinder ticket is never "build the proration engine." It's "how do we handle mid-cycle plan changes when the customer has unused credit?" Resolving a ticket produces a decision, recorded permanently on the ticket. It is not a slice of the build.
The map is an index, not a store. The map is a single issue labeled wayfinder:map. Child issues are the tickets. Each decision lives in exactly one place — its own ticket — and the map only gists it and links out. No duplicate copies drifting apart.
The map issue carries five sections: Destination (one or two lines naming the endpoint), Notes (domain context every session needs), Decisions so far (closed tickets, gisted and linked), Not yet specified (the fog), and Out of scope (work explicitly ruled out).
The Destination line does more work than it looks like. Get it vague and every downstream ticket inherits the vagueness.
Fog of war: the test that transfers everywhere
Wayfinder borrows the strategy-game concept of fog of war. Your tickets are the illuminated area — questions you can state precisely today. Beyond them is fog: "there's something about tax jurisdictions here, I can't phrase it yet." You don't plan a route through fog. You advance to the frontier, reveal more terrain, then decide.
The test for fog versus ticket is blunt: can you state the question precisely, right now? Yes means ticket. No means fog.
I now apply that test outside Wayfinder entirely. Half the tickets I used to write for client projects were fog wearing a ticket costume — vague enough that whoever picked them up spent the first hour re-deriving what the question even was.
Two more terms matter. The frontier is the set of open, unblocked, unclaimed tickets — decisions actually takeable right now. Claiming means assigning a ticket to yourself before working it, so two parallel sessions don't resolve the same question two different ways. I run parallel agents across git worktrees constantly, and the recurring failure is exactly that: two agents making incompatible decisions in the same twenty minutes.
The four ticket types, and the one that goes wrong
Every ticket carries a type label that determines which skill resolves it and whether you need to be in the chair:
| Type | Mode | What it resolves |
|---|---|---|
grilling |
Human in the loop | Questions settled by conversation — the default |
prototype |
Human in the loop | Behavioral or aesthetic questions needing a real artifact |
research |
Agent works alone | External facts blocking a decision; runs in parallel |
task |
Either | Manual prerequisites that unblock a decision |
Grilling is the workhorse — an adversarial Q&A that pushes on your plan until the branch resolves. I have grill-me and grill-with-docs from the same pack installed on this machine and use them weekly; grill-with-docs also updates CONTEXT.md and ADRs as decisions crystallize, which is exactly what a decision ticket should feed.
Research changes the economics. These fire as subagents, in parallel, while you're elsewhere. Four research tickets resolve in the time one grilling session takes.
Prototype exists because some questions can't be answered in prose. "Wizard or single form?" gets settled by a throwaway artifact — no tests, no abstractions, deleted once it has answered the question.
Task is the type that goes wrong most, and the skill's own docs admit it. A task ticket is manual work that unblocks a decision — provision the staging database, fetch API credentials. Agents consistently reinterpret it as an implementation step and start building production code inside the planning boundary. Watch your task tickets.
How a run goes, session by session
Session one: chart. You arrive with a fuzzy destination — "move billing to usage-based this quarter." The agent grills you until the Destination is one or two concrete lines, maps the frontier breadth-first (depth-first charting drags you down one branch until a sibling branch invalidates it), creates the map issue and the tickets you can phrase today, wires real blocking edges between them, drops the rest into fog, and fires the research subagents. Then it stops. Charting is one session.
Sessions two through N: work the map. Each session loads the map at low resolution — Destination, Notes, Decisions so far, frontier — not every ticket body. You claim one frontier ticket. The agent resolves it with the matching skill, posts the resolution as a comment, closes the ticket, gists it into Decisions so far, creates any tickets the resolution surfaced, graduates fog that's now sharp enough to phrase. And it stops.
That "and it stops" carries the whole system. One decision per session means every decision gets a fresh context window's worth of judgment. Sessions that keep going make three decisions on a window that only had good judgment left for one. This is the same discipline my rewrite manifest enforced by accident: small, verified increments, state written down, session discarded.
The map resolves. Eventually the frontier empties and the fog is gone. What you have is a web of linked decisions with the arguments intact — not a build plan. The final step converts it: in the pack's current release, /to-spec collapses the decisions into a specification and /to-tickets slices that into implementation work. My own install still shows the older /to-prd and /to-issues in ~/.claude/skills/, which tells me plainly my pack predates that rename — worth checking which pair you have before assuming Wayfinder is installed.
Setup is one pass: install the pack from the mattpocock/skills repo or the Claude Code plugin marketplace, then run /setup-matt-pocock-skills once per repo. It records which issue tracker the repo uses (GitHub via gh, GitLab via glab, local markdown for repos with no remote, or a prose description of your Jira/Linear workflow), your triage labels, and where domain docs live. That prose option is why calling it tracker-agnostic is fair: it doesn't ship a Jira integration, it ships a place to write down how your tracker works.
One design decision worth singling out: blocking relationships use the tracker's native dependency features, never a convention in the issue body. If "Blocked by: #42" is text in a description, only the agent that wrote it understands it. If it's a real blocking edge, GitHub renders the dependency graph and the frontier becomes something you can see.
How it differs from spec-driven development
Spec-driven frameworks — Spec Kit, Kiro, OpenSpec, which I ran as a daily driver for a stretch — treat the spec as the persistent source of truth. Wayfinder sits upstream of all of them: it's what you run when there's too much fog to write a spec at all. And its spec output is deliberately disposable — a milestone, not a maintained document.
That's the inversion worth keeping: traditional spec-driven development says the document is permanent and the reasoning is disposable. Wayfinder says the reasoning is permanent and the document is disposable. Having watched what happens to spec documents six months on, I think Wayfinder has it the right way around.
When I would not reach for it
Planning fits in one session. Most work qualifies. Use /grill-with-docs and be done in forty minutes; a map, four ticket types, and claiming conventions are pure overhead for a bounded feature.
The route is clear and only the work is large. Big is not the trigger — foggy is. My 84-post rewrite was large but never foggy; a manifest and batch discipline covered it. A twelve-week migration where you know every step needs parallel implementation agents, not charting.
You don't have a tracker you actually use. The local-markdown fallback works, but you lose native blocking edges and the visible frontier, which is most of the mechanical value.
You find adversarial Q&A draining. The grilling is exhausting — every question arrives as three paragraphs. A CLAUDE.md instruction to ask one short question at a time helps, but doesn't fully fix it. Budget for that before charting a twenty-ticket map.
For session-to-session continuity on work that doesn't need a full decision map, the handoff skill is the lighter tool, and none of this replaces basic context management on long sessions — a bigger window buys room, not continuity.
The reframe I'm keeping either way: stop writing plans, start closing questions. A plan is a claim about a future you can't see. A closed decision ticket is a fact with the argument attached, and it survives every context reset. Open your current project's plan document and count which lines are decisions with reasoning behind them and which are guesses in a confident voice. The guesses are your fog — and now you know how much of the map you never charted.
Wayfinder is one of dozens of skills I've vetted against real project work. If you're deciding which ones deserve a slot in your own setup, my agent skills marketplace is where I keep the ones that earned their place.
