/wayfinder 技能

它的作用

wayfinder 承担对一个智能体来说太大的任务 会话. This is an idea whose destination you can name but whose route you cannot yet see. Wayfinder charts it as a shared map of 决策任务 on your issue tracker, then resolves the tickets one at a time until the route is clear.

It plans and does not build. Every ticket asks a question, and the answer is a decision, not a slice of a build. The map is finished when nothing is left to decide before someone builds the thing. This rule separates a wayfinder ticket from an ordinary implementation ticket, and it is the rule agents break most often. When the map clears, wayfinder hands off and does not continue into code.

何时使用

你通过输入 /wayfinder; the agent 不会自动调用它。

It is the heaviest flow in the set, so the trigger is narrow. The effort must be larger than one agent session can hold, and the route to the destination must be unclear. The split is session count: /grill-with-docs 用于单会话规划， /wayfinder 用于多会话规划。

Greenfield is not a requirement. People use wayfinder routinely on legacy and half-built codebases, and it can be more useful there, because much of the fog is "what is already true here" rather than "what should we do".

前置条件

The map and its tickets live on the repo's issue tracker, so wayfinder needs the tracker setup from setup-matt-pocock-skills. That step writes a "Wayfinding operations" section. The section describes how to express the map, its child tickets, blocking edges, and frontier queries on GitHub, GitLab, or local markdown. Wayfinder finds that doc through the pointer in your CLAUDE.md / AGENTS.md, not at a fixed path. With no tracker configured, it falls back to local markdown files.

The tracker does real work. Its native blocking links show the frontier in the tracker's own UI. On a tracker without native dependency links (a self-hosted Gitea, say), wayfinder infers blockers from the map text. That works, but you must supervise it more closely.

地图、迷雾与前沿

这个 map 是一个标记为 wayfinder:map, and its tickets are its child issues. It is an 索引，不是存储. A decision lives in exactly one place, its ticket, and the map only gives a one-line summary and a link. A session loads the map at low resolution and opens individual tickets when it needs them. This lets a map keep growing without every session loading its whole history.

The map has four sections:

• Destination. What the end of this map looks like. You name it first, before any ticket exists, because the destination fixes the scope you measure every ticket against.
• Decisions so far. One line per closed ticket, each with a link to where the detail lives.
• Not yet specified. This is the 战争迷雾: decisions you can tell are coming but cannot yet phrase sharply. The test for fog versus ticket is whether you can state the question precisely now, not whether you can answer it. When you resolve a ticket, the fog ahead of it clears, and anything you can now specify graduates into a new ticket.
• Out of scope. Work beyond the destination. Fog only gathers toward the destination, so out-of-scope work stays closed and never graduates.

这个 frontier is the set of open, unblocked, unclaimed tickets (the edge of the known). A session claims a ticket by assigning it to itself before it does any work. The assignee is the claim, so concurrent sessions skip that ticket. Sessions refer to tickets by name, never by a bare #42, because a wall of issue numbers is hard to read in narration.

四种决策任务类型

每个任务都带一个 wayfinder:<type> label. Each ticket is either 人机协同（HITL） (worked with a human who speaks for themselves) or AFK (driven by the agent alone). A 人机协同（HITL） ticket resolves only through the live exchange. An agent that answers its own 追问审视 问题破坏了它。

task 是唯一会 does rather than decides. It belongs on the map only because it unblocks a decision, never because it delivers part of the destination. This type goes wrong most often in practice. Agents read it as an implementation step and start to write product code inside the map.

研究是 一个会话一个任务.

常见问题

这与 /grill-with-docs？我应该先开始哪一个？ 是会话数，不是项目规模。 /grill-with-docs 是单会话规划；wayfinder 是多会话规划。如果你能在一次对话中装下全部， 追问审视 is cheaper and better, and wayfinder is slower and denser for that case. The community shorthand is that wayfinder only makes sense if the work does not fit into a single session. This is by far the most-asked wayfinder question. People keep asking it because the skill descriptions do not tell you where your own task sits on that line. You have to judge the session count yourself.

当它问「目的地」时，指的是这次会话的结束还是万事的结束？ The end of the whole map, not just the first session. The question reads ambiguously, but wayfinder is a multi-session tool by definition, so a session-scoped answer never makes sense. Typical destinations are a spec to hand off, a decision to lock before planning starts, a proof of concept, or an in-place change such as a data migration.

The map is cleared. Didn't wayfinder already write the spec and make the tickets? Why do I still need /to-spec and /to-tickets? 不。Wayfinder 的任务是决策任务，地图关闭时它们也都关闭了。剩下的是满是关联决策的地图，它不是构建计划。 to-spec collapses those linked decisions into one spec (/to-spec #<map_issue>), and to-tickets slices that spec into tracer-bullet implementation tickets. If you loop the map straight into implement, you skip the collapse and lose the linked detail. Go straight to implementation only when the effort turned out small. Some people run the shorter pipeline and report that it works. The two extra steps give you an explicit spec that a reviewer or a colleague can read, which matters more when you do not work alone.

我的智能体在 wayfinder 会话中途开始写生产代码。 This is the most-reported failure with this skill, and a real gap in the skill causes it. You can override wayfinder's "plan, don't do" default in the map's 笔记. But the agent writes the Notes, so the constraint and its exemption live in a file that the constrained agent owns. 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. The skill has no hard stop for "I meant the default." Until it does, read the Notes on any map you did not chart yourself, keep implementation in separate sessions, and treat any wayfinder:task 看起来像构建切片被误打。

我绘制了 27 个任务，当我画到第十三个时，其余的已经不再有意义了。 This question is verbatim from a user report, and others report the same outcome. By default, wayfinder plans comprehensively. When later tickets rest on assumptions that earlier tickets invalidate, the map falls into the waterfall trap that critics accuse the skill of. Two things help. First, scope the map to a bounded destination, not to the whole product. Users report that maps scoped to one defined epic behave better than a sprawling "implement V1". The goal is to ship small increments, not to plan something very big. Second, prototype aggressively. The route stays current because cheap concrete artifacts expose uncertainty before implementation depends on it. Wayfinder is "prototypemaxxing", not "planmaxxing".

我能并行处理几个任务吗？ The frontier shows you which tickets you can take, and blocking edges make parallel work safe on paper. In practice, one ticket at a time is the safer default. If you work two grilling tickets at once, one session can ask you a question you just answered in the other, because the sessions share no context. Prototype tickets have a known gap too. One user reported an agent that built three UI variations, chose one itself, and closed the ticket. That choice is yours, and the skill does not yet say so clearly enough. If you do run tickets in parallel, review the dependency graph yourself first.

我必须使用 GitHub Issues 吗？ No. Any issue tracker works. GitHub has the best support, because its native sub-issues and blocking relationships make the frontier visible without opening the map. People also use GitLab, Linear, Jira and local markdown. There are two caveats. On a tracker with no native blocking, wayfinder infers the dependency graph from text, and you must correct it by hand. Local markdown puts the artifacts in your repo, which is not recommended, because material stored in the repo tends to persist by accident. Open-source maintainers hit the opposite problem (public trackers fill up with agent-generated planning tickets) and often choose local markdown anyway.

审问让人精疲力竭。每个问题都有三段长。 This is the sharpest open complaint about wayfinder, and nobody has fixed it yet. One user broke it down this way: the verbosity itself causes decision exhaustion, and the length hides why the agent asks a question, so you lose the chain from decision to decision as the map grows. The verbosity looks like a property of the current set of models rather than of the skill. Users try two mitigations: a lower 推理投入, and a plain-language instruction in your global CLAUDE.md. Expect to think hard here anyway. Wayfinder demands a lot of thinking from you, and that is most of its purpose, not a defect.

一个我已经关闭的决策被证明是错的。我应该编辑旧任务还是新建一个？ There is no official guidance, and the agent's default is unhelpful. It tends to design around the bad decision instead of challenging it, so you must steer it yourself. What works is to tell wayfinder plainly what changed. It then updates the map, revises the affected tickets, and comments on the closed ones. You can recover from scope changes mid-map. But if you designed a map to change, that is a sign the scope is wrong.

原来的 decision-mapping 去哪了？ It is this skill. v1.1 renamed it to wayfinder, and you invoke it as /wayfinder. "Decision map" was jargon, and it was also inaccurate, because only one of the four ticket types is a decision by itself. The new name gave the skill one consistent vocabulary (destination, fog of war, frontier, the map) instead of an invented term on top. The unit kept the word "decision": a wayfinder ticket is a 决策任务, so that people do not read it as an implementation ticket.

做到以下就算成功

• 目的地被写下并达成一致，早于任何任务存在。
• 每个开放的任务读起来都是一个问题。任何读起来像「构建 X」的任务，要么是打错了，要么属于地图的下游。
• You can look at your tracker and see which tickets are takeable without opening the map, because native blocking shows the frontier.
• A session resolves one ticket, posts the answer as a resolution comment, closes it, and adds one line to the map's 迄今的决策。然后它停下来。
• 尚未规格化 shrinks over time. When fog graduates into a ticket, it leaves that section and does not appear in both places.
• When the opening breadth-first grill finds no fog at all, the skill stops and tells you the effort is small enough to skip the map.
• The session that finishes the map points you toward a spec, not a pull request.

在流程中的位置

wayfinder 是一个 情境入口, not the default starting point. Most work still starts on the grill-led idea → ship chain. You use wayfinder when the idea is too big to hold in one session. It rejoins that chain at to-spec, because a cleared map hands off and does not build.

Most of the work happens in other skills that wayfinder schedules. 追问审视 and domain-modeling 解析默认任务类型， prototype resolves the tickets that talk cannot settle, and research 作为 子智能体 so its reading stays out of your session. handoff moves work in and out: into a map from a conversation that grew too big, and out of a map when a side quest appears mid-session. For anything else, ask-matt 路由整个技能集。