Wayfinder 是一个用于处理“任务过大、路线不明”情形的技能。它的核心思路是寻路而非直奔目的地：当一件事超出单次会话能容纳的规模、且从这里到终点的路径还看不清时，Wayfinder 先寻找这条路，而不是直接开工。
用途与定位
Wayfinder 把工作组织成一张“决策票据地图”，每张票据是一个问题，其答案是一个决策，或某个决策所等待的事实。每个会话解决一张票据，直到没有待决事项为止。它强调“规划而非执行”：票据产出的是决策，不是交付物。当产生“该开始动手了”的冲动时，正是到达地图边缘的信号，应带着这些决策交接给 spec-driven-planning（或 spec-driven-implementation）；某项工作可在其地图的 Notes 中覆盖这一约定。它同样强调“不要描绘看不见的东西”：在第一个问题回答之前就写出横跨数月、按阶段划分的完整任务清单，只是把猜测装扮成计划；只应为当下能清晰陈述的问题建票据，其余留作迷雾。
适用场景
工作跨越的会话数超过单个上下文能容纳的量，且关键决策仍悬而未决；用户表示面对一个大任务不知道从何开始；某个会话需要续接地图，例如“继续迁移计划”“下一步做什么”。不适用于单个会话就能规划的工作：如果绘制过程中没有浮现迷雾，应明确说明并直接使用 spec-driven-planning。
磁盘上的地图结构
地图存放在 docx/wayfinder/<effort>/ 下，包含 map.md 与 tickets/ 子目录（如 01-<slug>.md、02-<slug>.md）。map.md 只是索引而非存储，每个会话读取一次；票据细节只存在于票据文件中。map.md 包含 Destination（到达终点的样子，一两行）、Notes（领域、约束、每个会话应加载的技能、长期偏好）、Decisions so far（已解决决策的单行摘要加链接）、Not yet specified（范围内但尚不能清晰表述的迷雾，松散文字）、Out of scope（超出范围项及原因）。
票据格式与类型
票据大小为一次会话，带 type（grilling / research / prototype / task）、status、claimed、blocked_by 等元数据，正文包含问题标题与 Question 段（要解决的决策或调查及其对目的地的重要性）。Frontier 指开放的、未被认领且所有阻塞项均已关闭的票据；不应目测计算，而应运行 python3 <this skill>/scripts/frontier.py docx/wayfinder/<effort>。在人类阅读的一切内容中，票据应以标题引用、链接嵌在标题内，而不是“#3、#4、#7”这样的编号。
票据分两类模式：HITL（与人类实时交互解决，由人类自己作答）与 AFK（智能体独立完成）。绝不可代替人类回答 HITL 票据的问题。类型包括：grilling（HITL，用 grilling + domain-modeling 解决，默认类型）、research（AFK，用 investigate 后台智能体调查，发现写入 docx/research/）、prototype（HITL，当问题是“它应该长什么样/如何表现”时使用 prototype）、task（AFK 或 HITL，完成某个决策所等待的手工工作，如获取访问权限、运行探索查询、注册以评估 API；记录事实而非决策；仅人类能做的步骤用 wizard）。
使用方式
首次会话绘制地图：用 grilling + domain-modeling 命名目的地以确定范围；广度优先铺开 frontier，扫描整个空间、浮现开放决策与当下可执行的第一步；若无迷雾浮现则无需地图，停下并说明；编写 map.md（Destination、Notes、空的 Decisions、将迷雾写入 Not yet specified）；写下当下能清晰陈述的票据，再第二轮接线 blocked_by，运行 frontier.py 检查；用 investigate 在后台启动 research 票据；然后停止——绘图是一个会话，不手工解决任何问题。
后续每个会话：读取 map.md 并运行 frontier.py，不逐张阅读票据；处理用户指定的票据，否则按在场者选择——人类在场时取第一张 HITL frontier 票据与其一起处理，同时在后台启动 frontier 的 research 票据，不把人类时间花在 AFK 工作上；人类不在场时取 AFK frontier 票据，并在结束时指出等待人类的 HITL 票据。开始前先认领：设置 claimed；认领只有在写入磁盘并被其他会话读取后才可见（若在其他克隆中工作，需提交并拉取）。随后解决票据（按需打开其他票据、加载 Notes 指定的技能），记录结果（在票据末尾追加 ## Resolution、设置 status: closed、在 Decisions so far 加一行），更新地图（为答案浮现的新票据创建并接线；把已变清晰的迷雾从 Not yet specified 移出；超出目的地的票据关闭并在 Out of scope 记一行；被决策作废的票据改写或关闭）。每个会话一张票据，research 例外可并行。
迷雾与票据的区分标准是“现在能否精确陈述问题”，而非“能否回答”；被阻塞的清晰问题仍是票据；不要把迷雾预先切成票据大小。
常见错误与修正
第一天就写五阶段任务清单——应只为清晰问题建票据，其余留作迷雾；票据写成“实现 X”——那是构建步骤，属于地图之后的规格；智能体自行回答 grilling 票据——HITL 票据须等待人类；在 map.md 中重述决策——只写一行摘要加链接，细节留在票据；一个会话解决三张票据——每会话一张才能让每个答案可审查。
来源说明
该技能改编自 mattpocock/skills 中的 wayfinder（MIT 许可），详见 references/NOTICE.md。