For a huge, foggy effort: a new project from scratch, or a feature build too big for one agent session, where you can't yet see the way from here to the end. That end is the destination: a Spec, a decision, or a change.
wayfinder charts a map in the Issue tracker: one Issue labelled wayfinder:map, with child Issues Matt calls decision tickets. Unlike the main flow's Tickets, each asks one question whose answer is a decision, not a slice to build. "Plan, don't do": it produces decisions, not deliverables.
The map holds the Destination, Notes, Decisions so far (one line per closed decision ticket, linking it), Not yet specified (the fog: questions you can tell are coming but can't phrase sharply yet) and Out of scope.
Each decision ticket has a type label: research, prototype, grilling (the default, a conversation with you) or task (manual work a decision waits on). Some are HITL (human in the loop: they need you, live); some are AFK (the agent works alone).
When to use it
Chart the map: you bring a loose idea. It interviews you to name the destination, then broadly to find the open decisions, creates the map and the tickets it can already state, and links which tickets block which. That's one session; it resolves nothing itself, but subagents take the research tickets.
Work through the map: you bring the map. It takes the first ticket on the frontier (open, unblocked, unclaimed), claims it by assigning it, resolves it, and stops. One ticket per session, except research tickets.
a loose idea
Chart the mapThat's one session
Work through the mapOne ticket per session, except research tickets.
to-specwhich turns the linked decisions into a buildable Spec
When the map clears, it hands off; it doesn't build.
When not to use it
For an idea you can hold in one session, use grill-with-docs. wayfinder is slower and denser: never for a well-scoped feature.
If charting finds no fog, you don't need a map; it stops and asks how you'd like to go on.
Not to build. When you feel the pull to just do the work, you've reached the edge of the map.
What it needs to start
An Issue tracker set up by setup-matt-pocock-skills. Without one, it falls back to Markdown files in the repo.
You. Only you can start it, and HITL tickets need you there to answer.
A loose idea, or an existing map.
What it creates
The map Issue and its decision tickets, with wayfinder: labels and blocking links.
For each resolved ticket: an answer comment, the closed Issue, and a line under Decisions so far.
For research tickets: findings on a research/<name> branch, pushed but never merged.
When the map clears, it hands off; it doesn't build. It merges onto the main flow at to-spec, which turns the linked decisions into a buildable Spec, then to-tickets and implement as usual.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt built wayfinder because planning itself outgrew one session. On The Pragmatic Engineer podcast (17 September 2026) he imagined grilling "a stripe clone" and said: "There's no way you can plan that in 150k tokens." So he asked how to run "grilling sessions that can be infinite length".
He told Latent Space (20 August 2026) what planning felt like before: "I was finding the planning stage really onerous, because I would have to be constantly thinking about my session management." His v1.1 release post (8 July 2026), where wayfinder graduated from in-progress to a mature Skill, names the limit: "You're either going to blow out of the agent's smart zone or even hit its context window limit."
How it works underneath
The design starts from a question about information flow. Matt asked what a grilling session needs when another session manages it. His answer: "the child probably needs to understand a vague overview of what else is happening, and they need their specific task." That gives two documents: the map for the overview, and the ticket for the task.
The map stays small on purpose. Its SKILL.md calls it an index, not a store: a decision lives in exactly one place, its ticket, and the map only gists it and links. Matt's Skill page gives the payoff: this "lets a map keep growing without every session loading its whole history."
Citations (87)
From snapshot/skills/wayfinder/SKILL.md, line 3: “Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.”
The words do work too. Version 1.1 renamed the Skill from decision-mapping, because "Decision map" was "jargony and inaccurate". The changelog says the new words give "one coherent leading-word frame". Once Matt had "fog of war" and "map", he found that "it really leads the agent into the right idea."
The Issue tracker does real work as well. Native blocking links are "essential because it renders the frontier visually in the tracker's own UI", so you see which tickets are takeable without opening the map.
A real example
The v1.1 post pictures a map as it really lives: a GitHub issue with blocking relationships.
A wayfinder map as a GitHub issue with blocking relationships, from Matt's v1.1 post From aihero.dev, 30 October 2026.
The same post describes a real map in the Sandcastle repo, "investigating whether to pull in the AI SDK as a dependency".
On the podcast Matt said: "I've had maps that have, you know, 50, 100 tickets or something until I finally reach my destination." He uses it away from code too: for course planning, and "to build a garden office in my garden".
Richard MacManus of Latent Space tried it "on a project to rearchitect my personal website", which had "20+ years of content to re-organize".
Richard MacManus working through his website rearchitecture with wayfinder From latent.space, 30 October 2026.
Where it goes wrong
Building inside the map. Matt's Skill page (updated 24 August 2026) calls this "the most-reported failure with this skill". The map's Notes can switch off "plan, don't do", but the agent writes the Notes. One agent wrote "this map carries execution" there, and in later sessions "read that line back as permission and built on a live server." The page's advice: "read the Notes on any map you did not chart yourself".
Waterfall. One user charted 27 tickets, and "by the time I got to the thirteenth, the rest no longer made sense." The page's fix is to scope the map to a bounded destination and prototype hard: "Wayfinder is "prototypemaxxing", not "planmaxxing"." On the podcast Matt answers the waterfall charge the same way: "I do a lot of upfront aggressive prototyping".
Grilling itself. Before v1.1, students reported wayfinder "grilling itself instead of the human". v1.1 fixed it by marking every ticket type HITL or AFK.
Research closed unseen. In issue #1241 (9 October 2026, still open), a user's research findings were posted, "the ticket closed and the map edited before the human had seen them."
Parallel tickets. With two grilling tickets open at once, "one session can ask you a question you just answered in the other", since the sessions share no context.
A map you didn't need. In a post on X (8 October 2026), Matt wrote "Never start with /wayfinder". The work can turn out "way simpler than you thought", and then "you've created the map and tickets, and you realise you don't need them." His advice for a medium-large change: start with a /grill-with-docs session, and if planning starts to get out of hand, say "/wayfinder let's turn this into a map". The post is newer than the Skill page and the v1.1 post (8 July 2026), which said wayfinder was "designed to replace /grill-with-docs in many situations". But the current SKILL.md (29 October 2026) still charts from "a loose idea", and stops by itself: "If this surfaces no fog", you don't need a map. So the post is advice on when to reach for wayfinder, not a change in what it does.
start with a /grill-with-docs session
if planning starts to get out of hand
/wayfinder let's turn this into a map
Never start with /wayfinder
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick a foggy effort for the yoga-studio site: say, members buying class passes and paying online.
Follow Matt's October 2026 advice and start with grill-with-docs. If the questions keep spreading past one session, type /wayfinder let's turn this into a map.
When charting stops, open your GitHub Issues. Read the map's Destination, then find the frontier from the blocking links alone, without opening the map.
In a fresh session, run /wayfinder with the map's number. Let it claim one ticket; if it's a grilling ticket, answer its questions until it resolves. Then read its resolution comment and the new line under Decisions so far.
Read the map's Notes. If they say the map carries execution, ask yourself whether you wrote that.
From snapshot/skills/wayfinder/SKILL.md, line 75: “Every ticket is either HITL (human in the loop, worked with a human who speaks for themselves) or AFK, driven by the agent alone.”
From snapshot/skills/wayfinder/SKILL.md, line 112: “If this surfaces no fog (the way to the destination is already clear, the whole journey small enough for one session), you don't need a map.”
From snapshot/skills/wayfinder/SKILL.md, line 125: “Record the resolution: post the answer as a resolution comment, close the issue, and append a context pointer to the map's Decisions-so-far.”
From snapshot/skills/ask-matt/SKILL.md, line 52: “Where /grill-with-docs sharpens an idea you can hold in one session, wayfinder is for the idea you can't, and it's slower and denser, so save it for exactly that, never a well-scoped feature.”
From snapshot/skills/ask-matt/SKILL.md, line 54: “When the map clears, it hands off, it doesn't build: merge onto the main flow at /to-spec, which collapses the map's linked decisions into a buildable plan, then /to-tickets and /implement as usual.”
From snapshot/skills/wayfinder/SKILL.md, line 115: “capturing its findings on a throwaway research/<name> branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged.”
From snapshot/web/latent.space/p-wayfinder-skill.md, line 81: “once I had the idea of ‘fog of war’ and ‘map’, I realized those two terms actually work really nicely together, and it really leads the agent into the right idea.”
From snapshot/skills/wayfinder/SKILL.md, line 69: “Blocking uses the tracker's native dependency relationship: essential because it renders the frontier visually in the tracker's own UI, so the human sees what's takeable without opening the map.”
From snapshot/web/aihero.dev/skills-wayfinder.md, line 105: “One user watched an agent write "this map carries execution" into its own Notes. In later sessions the agent read that line back as permission and built on a live server.”
From snapshot/web/x.com/mattpocockuk-status-2108216899439894574.md, line 26: “A failure mode of /wayfinder is that you start grilling and the solution turns out to be way simpler than you thought. Why is this bad? Because you've created the map and tickets, and you realise you don't need them.”
From snapshot/skills/wayfinder/SKILL.md, line 125: “Record the resolution: post the answer as a resolution comment, close the issue, and append a context pointer to the map's Decisions-so-far.”
