Skills v1.1: Wayfinder, the SDLC flow, and naming the artifact right
TL;DR
Matt Pocock's v1.1 skills release turns a planning-heavy skill
collection into a full software development lifecycle and introduces
Wayfinder, its highest-value new idea: when a plan is
too big for one agent session and wrapped in fog (the route to
the destination isn't visible yet), you don't grill-and-spec in one
sitting — you chart a persisted shared map of typed,
session-sized investigation tickets on the repo's issue tracker and
resolve them one at a time until the route is clear, then
convert the map into a spec. Each ticket is typed by how the unknown
resolves — Research (AFK), Prototype (HITL), Grilling (HITL, the
default), or Task — and by whether a human must be present
(HITL vs AFK), with blocking edges so no decision is made before its
prerequisite. The rest of the release is refinement of the same author's
existing system: the two flow skills are renamed
/to-prd → /to-spec and
/to-issues → /to-tickets (a breaking change he frames as
good friction because the old names were wrong — a "PRD" was
leaking non-PRD content, and "issues" was tracker-biased); a
deliberately tiny /implement skill is added to name the
main flow end-to-end (grill/wayfinder → to-spec → to-tickets → implement
→ code-review); /code-review gains Martin Fowler's named
refactoring smells as leading words that trigger the
agent's priors; grilling gets a confirmation gate and a
facts-vs-decisions distinction to stop it running past the human or
grilling itself; and TDD is demoted to reference-only (red-green,
refactor moved out to code-review). Everything is illustrated by the
actual on-screen SKILL.md files.
Concepts introduced
- Map-First Planning — the Wayfinder pattern's durable core: plan an oversized, uncertain effort by charting a persisted shared map of session-sized decisions and resolving them in dependency order before you spec — "find the way, don't charge at the destination."
- Resolution-Typed Tasks — classify each open item by how it resolves (research / prototype / grilling / task) and whether a human must be present (HITL vs AFK); the type routes the work and bars the agent from standing in for the human.
- Fidelity-Raising Prototype — raise the fidelity of a planning discussion by making a cheap, rough, concrete artifact to react to, rather than debating in the abstract; essential wherever "how should it look / behave" is the question.
Held, not dropped (touched but not yet their own page):
- Async/background research with primary-source
discipline — the
/researchskill's "follow every claim back to the source that owns it, not a secondary write-up," run on a background agent so you keep working. Overlaps Recency-Grounded Research; spin out only if a second source converges on the primary-source-over-write-up rule as its own principle. - Rename friction as good friction — deliberately accepting migration cost (delete + re-add skills) because the new name is more correct. A naming-precision theme adjacent to Spec-Driven Development; held pending a second instance.
- Grilling-skill robustness — the confirmation gate ("do not enact the plan until I confirm we've reached shared understanding") and the facts-vs-decisions leading-word fix that stopped the agent running straight into implementation or grilling itself. Folded into Leading Words and Agent Supervision rather than given a page.
- TDD scope-narrowing — TDD demoted to reference-material-only (red-green, one slice at a time), with refactoring moved out of the loop into code-review "so you don't overload the implementation." A process-boundary theme; held.
- Collaborative planning maps — Wayfinder maps live in GitHub issues, so they're shareable across a team. Adjacent to Shared Review Surface; held.
Key claims
- When a plan is too big for one agent session and the route is unclear, chart it as a persisted shared map of session-sized tickets and resolve them one at a time until the way is clear — then spec. (best practice) — context: large, high-uncertainty efforts that would blow the agent's "smart zone" or context window; overkill for a plan that fits one session. → Map-First Planning
- Name the destination first — it is "the first act of charting" and shapes every ticket. principle — a plan's target constrains its decomposition; naming it up front is durable across domains (the skill itself calls the map domain-agnostic). → Map-First Planning
- Type each open item by how it resolves (research / prototype / grilling / task) and whether a human must be present (HITL / AFK); the agent must never stand in for the human's side of a HITL ticket. principle — the HITL/AFK line is durable: an agent answering its own grilling questions has defeated the point of grilling. → Resolution-Typed Tasks
- Raise the fidelity of a discussion by making a cheap, rough, concrete artifact to react to, rather than discussing in the abstract — essential for anything front-end. principle — a concrete referent lowers ambiguity regardless of tool; the logic-vs-UI split is the contextual part. → Fidelity-Raising Prototype
- Name the artifact for what it actually is: "PRD" leaked non-PRD content, so the true, broader name is "spec"; "issues" was tracker-biased, so "tickets." (best practice) — context: the name of a planning artifact steers what gets produced into it; a precise name is worth a breaking rename ("good friction"). → Spec-Driven Development
- Invoke a well-cited canon's vocabulary (Fowler's refactoring smells) as leading words — one sentence per smell — to unlock capability already deep in the model's priors; it repeats the term back and acts on it. (best practice) — context: steering toward concepts with established terminology the model already knows; "~10 lines, outrageously useful." → Leading Words
- A skill can earn its place by naming a step even
when it's near-trivial:
/implementis deliberately tiny and leans on the agent's priors and the harness. (best practice) — context: a recurring, loaded step where a small skill's value is legibility of the flow, not new instruction. → Minimal Skill Surface - Put refactoring in the code-review stage, not inside the TDD loop, so you don't overload the implementation; TDD becomes red-green reference material only. (best practice) — context: the author's own preference for AFK-runnable TDD; presented as taste ("I tend to think"), not law. → Step Isolation
- The grilling agent should ask one question at a time and stop at a confirmation gate before enacting the plan. (best practice) — context: interactive planning where the agent otherwise batches questions or runs straight into implementation; the fix was telling it why, plus an explicit gate. → Leading Words / Agent Supervision
- The video states the skills repo is "up to like 160K stars" with "7 million downloads on skills.sh," and that grilling-itself was "especially happening with Fable." observation — the source's claims about external, groundable facts (star count, download count, a named model's behavior); recorded as claimed, for later verification, not adjudicated here.
Why this builds on the existing graph
This capture is the same author (Matt Pocock)
iterating on the skill system already documented in the vault — Leading Words, Step Isolation, Minimal Skill Surface, Spec-Driven Development, and Agent Task Graph all trace to his prior
videos. So the dominant stance is
builds_on/refines, with genuine
novel extensions:
- Corroborates + extends Leading Words. The Fowler-smells-in-code-review move is a second application of the same principle already on the page (leading words trigger priors and the agent repeats the term back). The facts-vs-decisions fix in grilling is a third. No contradiction — convergent evidence from the concept's originating author.
- Extends Spec-Driven
Development.
/to-prd → /to-specoperationalizes "name the artifact precisely," and the five-step flow (grill/wayfinder → to-spec → to-tickets → implement → code-review) is the SDD pipeline made explicit end-to-end. - New concrete instance of Agent Task Graph. Wayfinder
materializes the blocks/blockedBy graph as GitHub issues + sub-issues,
each scoped to one agent session and typed — a third instance
alongside Claude Code's Task System and
seeds/sd plan, and the first that types its nodes by resolution mode. - Novel above the graph. Map-First Planning (planning under fog — decomposing the unknowns, not just the work) and Resolution-Typed Tasks (HITL/AFK + resolution-mode typing) are not reducible to the dependency-graph concept; and Fidelity-Raising Prototype is a distinct planning primitive. These get their own pages.
No contradicts stance: nothing here is in tension with
an existing vault claim.
Illustrated walkthrough
Visual coverage is low confidence (sampler audit): the largest un-illustrated stretch is ~91 s, concentrated in the 120–247 s window (frames only at 120 s, 180 s, 247 s) covering the grilling-fix narration and the run-up to the SDLC flow. Slide or terminal changes in those gaps were not sampled — absence of a frame there is not evidence of a static screen. The walkthrough below is keyed to frames I could read.
- t=0:27 — the release PR (
f0003). GitHub PR #464, "v1.1: planning-skills unification (breaking) + wayfinder graduation," 8 commits intomainfromrelease/v1.1, 57 files changed, "Ready to merge." The body spells out the renames —/to-prd → /to-spec;/to-plan/to-issues → /to-ticketswith/to-issuesdeleted — and notes/to-ticketsemits tickets "each declaring its blocking edges" as **one medium-agnostic artifact that reads two ways: a local file (tickets.md, edges as text, worked top-to-bottom) or a real tracker (edges as native blocking links, so any unblocked ticket is on the frontier and several agents can run at once)." A routing line readsidea → /to-spec → /to-tickets → /implement.
- t=0:44 — repo layout (
f0013). Theskills/tree shows bucketsdeprecated,engineering,in-progress,misc,personal,productivity. The top commit is telling: "docs: settle wayfinder as a situational on-ramp, not the main entry flow" — i.e. despite the excitement, Wayfinder is positioned as situational, not the new default. Sibling commits: "Graduate wayfinder to engineering; unify changesets for v1.1" and "refactor: unify planning skills into /to-spec + /to-tickets." - t=4:07 — the main flow, finally named
(
f0023). A five-step diagram: 1 grill-with-docs → 2 to-spec → 3 to-tickets → 4 implement → 5 code-review. This is the "what is the flow?" answer people kept asking for;/implementexists mainly to name step 4. - t=7:00 — code-review as a smell checklist
(
f0028). Theengineering/code-review/SKILL.mdreads "Each smell reads what it is → how to fix; match it against the diff:" then a bulleted catalog — Mysterious Name (name doesn't reveal what it does → rename; if no honest name comes, the design's murky), Duplicated Code (→ extract the shared shape), Feature Envy (a method reaching into another object's data → move it), Data Clumps (fields that travel together → a type wanting to be born), Primitive Obsession (→ give the concept its own small type), Repeated Switches (→ replace with polymorphism)… The claim is that these names are already deep in the model's priors, so a one-line description per smell is enough to unlock them. - t=8:04 — the flow, revised (
f0030). Step 1 becomes "grill-with-docs OR wayfinder" — the new pre-spec fork. - t=8:25 — the Wayfinder skill (
f0031).name: wayfinder, and notablydisable-model-invocation: truein front-matter. Description: "Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear." Body: "A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the destination isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a shared map on the repo's issue tracker, then works its tickets one at a time until the route is clear." And: "The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic." Next section header:## Plan, don't do. - t=9:52 — ticket types (
f0043).## Ticket Types: "Every ticket is either HITL — human in the loop, worked with a human who speaks for themselves — or AFK, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this)." Then the four types: Research (AFK — read docs / third-party APIs / local knowledge bases, write a markdown summary as a linked asset), Prototype (HITL — raise the fidelity of the discussion with a cheap rough artifact; use when "how should it look / behave" is the key question), Grilling (HITL — one question at a time via/grilling+/domain-modeling; the default case), Task (HITL or AFK — manual work that must happen before a decision can be made). - t=11:22 — the research skill (
f0051).name: research. Spins up a background agent so you keep working while it reads. Its job: "1. Investigate the question against primary sources — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it. 2. Write findings to a single Markdown file, citing each claim's source. 3. Save it where the repo already keeps such notes; match the existing convention."