🎯 The constraint being removed 0:00
The opening diagnosis is the most valuable sentence in the video, and it is aimed at the author's own previous tools:
"The existing planning tools that I was using and playing around with, even ones that I've created, felt too constrained, too tied to a single session… And because of that, I was kind of constraining the stuff I was building to fit AI, which doesn't feel right."
That second clause is the real problem. Not that the plan gets lost — that the ambition gets trimmed to whatever survives one conversation. Anyone who has silently narrowed a piece of work because it would not fit in one agent session has hit this without naming it.
The failure mode he describes is specific and recognisable. You break the work into chunks ahead of time so each fits a session. Then mid-session you hit a question you cannot answer, you are lost in fog, and the whole time you are "managing the smart zone" — trying not to burn tokens before the useful part of the context window degrades. The plan competes with the work for the same scarce resource.
🗺️ The map, and why the tracker 2:10
The structural move: the plan stops being conversation state and becomes an artifact in your issue tracker. A parent issue is the map; child issues are the decision tickets.
He shows a real one — a map with 12 sub-issues, decisions resolved inside their tickets, with a one-line summary written back up to the parent.
The skill's own text is stricter than the video about why. It calls the map "an index, not a store" — a decision lives in exactly one place, its ticket, and the map only gists it and links. That constraint is what stops the parent issue growing into another context-window problem.
Using the issue tracker rather than a bespoke tool is the quiet, correct decision here. Persistence, permissions, comment threads, notifications, audit history and cross-linking already exist and are already trusted in most organisations. Nothing new to run, nothing new to back up, and the plan is visible to people who will never open an agent session. He notes the skills are tracker-agnostic — GitHub, Linear, Jira, configured via a setup step.
🎟️ Decision tickets 13:15
The distinction that resolves most of the confusion people bring to this:
| Ticket kind | What it contains | When it exists |
|---|---|---|
| Decision ticket (Wayfinder) | A question whose resolution is a decision | During planning, on the map |
| Implementation ticket (normal) | A slice of the build to execute | After the spec, downstream |
The skill enforces this explicitly: "Wayfinder is planning by default… absent that, produce decisions, not deliverables." It even names the tell — "the pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off." That is a genuinely useful heuristic independent of the tool.
Each ticket is sized deliberately: the skill specifies a body "sized to one 100K token agent session". Tickets are claimed by assignment before any work begins, so concurrent sessions skip them — that is what makes parallel work safe rather than just possible.
Blocking uses the tracker's native dependency relationship, and the reason given is good: it renders the frontier visually in the tracker's own UI, so a human can see what is takeable without opening the map at all. A body convention is the fallback only when the tracker lacks native blocking.
🌫️ Fog of war as a design rule 3:36
The central metaphor, and it earns its place rather than decorating the idea. The map is deliberately incomplete. Tickets you can state now form the frontier; everything else sits in fog until a resolution clears it.
"It knows that you can't make your way cleanly to the destination. You have to clear the fog of war."
The skill supplies a crisp test the video does not: "The test is whether you can state the question precisely now — not whether you can answer it now." Sharp question, even if blocked, becomes a ticket. Vague area becomes a "Not yet specified" note. And it warns against pre-slicing fog into ticket-sized pieces, because one foggy patch may graduate into several tickets or none. That single rule is portable to any planning method.
There is also an Out of scope section, distinguished carefully: fog gathers only toward the destination, so work beyond it is not fog and never graduates.
🧩 Four ticket types 7:41
Each ticket carries a wayfinder:<type> label, and the type determines how the session runs.
| Type | Purpose | Use when |
|---|---|---|
| Research | Surface a fact a decision waits on; runs in a subagent and reports back | Knowledge outside the working directory is needed |
| Prototype | Build something cheap and concrete to react to | "How should it look / behave" is the question |
| Grilling | One-question-at-a-time discussion | The default case |
| Task | Real-world work that unblocks a decision | Nothing to decide until something is provisioned or done |
The Task type is the one that makes this usable outside pure software. The skill is precise about its boundary: it is "the one type that does rather than decides — and it earns its place by unblocking a decision, not by delivering the destination." Signing up for a service so its API can be judged; provisioning access; moving data so its shape can be seen. Resolution records facts later tickets depend on — credential locations, new URLs, row counts.
His own example of that generality: he used Wayfinder to plan a garden office — site survey, contractors, research. The skill backs this up, calling the map "domain-agnostic — engineering work, course content, whatever fits the shape."
👥 The split the video omits 7:44
Reading the skill source alongside the video surfaces a distinction that matters more than the four types, and it never gets stated on camera.
Every ticket is either HITL or AFK. Human-in-the-loop tickets resolve only through live exchange with a person who speaks for themselves. AFK tickets are driven by the agent alone. Research is AFK; Prototype and Grilling are HITL; Task is either.
And the skill names the failure mode explicitly: "the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this)."
And the skill names the failure mode explicitly: "the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this)."
Why this is the most important line in the whole system. The value of a decision map is that decisions were actually made by someone accountable for them. An agent that fills in both sides of a grilling session produces a map that looks complete and encodes nobody's judgement — plausible, traceable, and hollow. If you adopt one rule from this, make it that one. Anyone evaluating this for team use should know the constraint exists, because the video's framing ("it orchestrates it all for you") reads as more autonomous than the skill actually is.
Related, and also unmentioned: the skill ships with
disable-model-invocation: true, and its agent config sets allow_implicit_invocation: false. Wayfinder cannot start itself — a human has to invoke it deliberately. Sensible for something that creates issues in your tracker.🏗️ Why it isn't waterfall 8:22
He raises the strongest objection himself rather than waiting for the comments — that this looks like a lot of up-front planning.
"Huge amounts of low-fidelity upfront planning… A prototype is a high-fidelity way to get feedback on what you're actually building."
The rebuttal holds, and it is worth stating in general terms. Waterfall's failure was not planning ahead — it was planning ahead entirely on paper, then discovering on contact with reality that the paper was wrong. Prototype tickets inject reality checkpoints during planning. Combined with the fog rule — never chart what you cannot yet see — the plan is continuously corrected by contact rather than fixed at the start. That is close to the opposite of waterfall.
🔗 Primary sources over summaries 10:53
The most underrated benefit in the video, and he frames it as a fix for a weakness in his own earlier approach.
Specs generated from a map link back to the decision tickets that produced them. So when the agent — or a person — is confused about why something is specified a certain way, they can open the original discussion.
"That was always a weakness with grill-with-docs, which is that you were really relying on the spec to be the source of truth, but the spec is always just a summary of what was actually said in the meeting."
This is the same principle that governs good research and good journalism, applied to engineering artifacts. A summary loses the reasoning that produced it, and reasoning is exactly what you need when circumstances change. Keeping a live link from conclusion back to source means a decision can be re-examined rather than merely obeyed or overturned blindly. It is also the strongest audit argument for this approach in a regulated setting.
A telling detail he laughs past: the first spec generated from one map exceeded GitHub's character limit. That is a real operational constraint, not a joke — dense maps produce documents big enough to break their own container.
🗑️ Disposable specs 13:27
His most contrarian position, and he flags that it will annoy people:
"I close the issue containing the spec and the spec is gone. It's gone from my repository. I rarely if ever refer to it again. Once the spec is present in the code, then you can just delete the spec."
His reframing: a spec is not documentation, it is a destination document for multi-session work — scaffolding that exists so a long effort knows where it was heading.
The reasoning is coherent, but the deletion is doing less work than it appears. Under Wayfinder the spec is safely disposable precisely because the decision tickets survive — the reasoning still exists, in the tracker, linked. Deleting a spec without that substrate would destroy the record. Worth understanding as a package rather than adopting the disposal half on its own.
🧭 When not to use it 11:38
The FAQ opens with the objection that it is too much process, and the answer is refreshingly unambitious:
"If you think the work that you're doing can be completable and plannable in a single session, then plan it in a single session… Wayfinder is for the cases where you have the fog of war."
The selection rule is uncertainty, not size. A large but well-understood job does not need a map; a small job with genuinely unclear steps might. That is a better trigger than effort estimates, and it is unusual for a tool author to spend part of a launch video telling you when not to use the thing.
He is also clear that Wayfinder replaces one step rather than adding a layer: it slots exactly where grill-with-docs sat in his pipeline — map → spec → tickets → implement → code review.
🔍 Claims checked
| Claim | Result |
|---|---|
| Wayfinder exists in the public skills repo | skills/engineering/wayfinder/SKILL.md — read directly |
| Repo is public and permissively licensed | MIT, 195,978 stars, 16,887 forks, created Feb 2026 |
| Actively maintained | Last push 29 July 2026 — one day before the video |
| Grilling and prototype skills are real dependencies | Both present as separate skills, plus changesets referencing Wayfinder |
| Four ticket types: research, prototype, grilling, task | Exactly as described, with wayfinder:<type> labels |
| Research runs in a subagent | "Resolved by a /research subagent" |
| Issue-tracker agnostic | Tracker-specific operations are externalised; local-markdown is the default fallback |
| Works for non-coding work | Skill states "domain-agnostic… course content, whatever fits the shape" |
| HITL / AFK distinction | Never mentioned in the video — and it is the constraint that keeps the map honest |
| Skill cannot self-invoke | Not mentioned — disable-model-invocation: true, implicit invocation disabled |
| Tickets sized to one session | Skill specifies "one 100K token agent session" |
| Claiming prevents collisions | Assignment happens before any work; unassigned open ticket = unclaimed |
| "Works with any coding agent" | Plausible — skill is markdown with an OpenAI-format config; no compatibility matrix published |
| Community adoption (testimonials shown) | Screenshots shown on screen; individually unverifiable, though repo metrics support broad usage |
Overall: the video undersells its own tool. Every structural claim checks out against the source, and the skill's written text is more rigorous than the demo — the fog test, the index-not-store rule, the HITL guardrail, and the deliberate-invocation setting are all absent from the video and all worth knowing. This is the rare case where reading the primary source makes the thing look better, not worse.
Repository metadata, SKILL.md and agent config retrieved and verified 30 July 2026.
💡 Key takeaways
- The real cost of session-bound planning is trimmed ambition, not lost notes. You quietly shrink work to fit what one agent conversation can hold.
- Move the plan into the issue tracker. Persistence, permissions, history, notifications and cross-linking already exist and are already trusted — no new system to run.
- The map is an index, not a store. A decision lives in exactly one place — its ticket. The map only gists and links, which is what stops it becoming another context-window problem.
- Decision tickets ≠ implementation tickets. One resolves a question; the other executes a slice. Conflating them is the most common misreading.
- "The pull to just do the work is the signal you've reached the edge of the map." A useful heuristic regardless of tooling.
- The fog test: can you state the question precisely now? Not whether you can answer it. Sharp question → ticket, even if blocked. Vague area → a note, not a pre-sliced ticket.
- Blocking should use the tracker's native dependencies so the frontier renders visually in the tracker UI — a human sees what is takeable without opening the map.
- Claim before you work. Assignment marks a ticket taken so concurrent sessions skip it, which is what makes parallel planning safe rather than merely possible.
- Prototype tickets are what stop this being waterfall. Waterfall failed by planning entirely on paper; prototypes inject reality checks during planning.
- Task tickets earn their place by unblocking a decision, not by delivering the destination — which is what lets the method cover non-software work like site surveys and contractors.
- Every ticket is HITL or AFK — and the video never says so. The skill forbids the agent standing in for the human's side: "a grilling agent that answers its own questions has broken this."
- A self-answered map is worse than no map: plausible, traceable, and encoding nobody's judgement.
- Wayfinder cannot invoke itself.
disable-model-invocation: trueand implicit invocation disabled — sensible for anything that writes to your tracker. - Specs that link back to decision tickets let you re-examine reasoning, not just obey conclusions. A summary loses the reasoning; reasoning is exactly what you need when circumstances change.
- Disposable specs work only because the tickets persist. Adopt the deletion half without the substrate and you destroy the record.
- The trigger is uncertainty, not size. Known path, however large → single session. Foggy path, however small → map it.
🔗 Resources & links
- /wayfinder: Nothing is too big to plan anymoreSource video — Matt Pocock, 15:09
- mattpocock/skillsThe skills repo — MIT licensed, 195,978 stars
- wayfinder/SKILL.mdThe primary source — stricter and more informative than the video
- Wayfinder documentationLonger-form docs in the same repo
- prototype skillThe dependency that keeps Wayfinder from becoming waterfall
- grilling skillThe default HITL ticket type
🕐 Timestamp index
0:00Planning any size of work with an agent
0:09Even my own tools were too session-bound
0:17Constraining the work to fit AI
0:32You have to clear the fog of war
0:43Built on software fundamentals
0:56How he planned before: grill-with-docs
1:11Work bigger than the smart zone
1:30Hitting a question you can't answer
1:44Community reaction and a custom harness
2:10How big work gets planned
2:23Start point, destination, fog between
2:37Start with a grilling session
3:04What we're building is a map
3:15Each map node is a ticket, each ticket a session
3:28It's a single skill, works with any agent
3:36The frontier versus the fog
4:02It manages tasks and errands too
4:30Tracking decisions in the issue tracker
4:43A real map with 12 sub-issues
5:10Resolutions written back up to the map
5:26Tracker-agnostic: GitHub, Linear, Jira
5:39Deciding the destination first
6:02Invoking the skill on a real effort
6:24It asks what "done" looks like
6:39Seven tickets, only three takeable
6:54Working each ticket in a new session
7:04A handoff skill spawning subagents
7:26Chart the map, then walk each ticket
7:41Four ticket types
7:50Research tickets run in subagents
8:03Prototype tickets
8:22"Doesn't that look like waterfall?"
8:45Grilling tickets
8:55Task tickets: real-world work
9:08Blocking relationships between tickets
9:1814 of 17 done, and still not built
9:38Watching the frontier move
9:44Creating specs and tickets from a map
10:19The spec exceeded GitHub's character limit
10:31Where Wayfinder sits in the pipeline
10:53Specs link back to decision tickets
11:09The weakness in grill-with-docs
11:38FAQ: when should you use it?
12:09Wayfinder is for the fog of war
12:17Using it for a garden office
12:33"Isn't this spec-driven development?"
12:44A spec as a destination document
13:15Decision tickets versus implementation tickets
13:27He deletes the spec afterwards
14:02Chart your own foggy idea
14:36Starting without knowing how you'll get there