Reference · User-invoked · On-ramp（大而雾任务的入口）

wayfinder 速查

把「一个 agent 会话装不下」的努力画成工单系统上的共享决策地图，一次解决一张票直到路清。完整教学见 Lesson 0016；原文见 SKILL.md、三份 tracker 模板（ GitHub · GitLab · 本地）、 aihero.dev/skills-wayfinder。

一句话

任务大到、雾到一个会话装不下时：建一个 wayfinder:map 父 issue + 一排决策票子 issue，一次会话解决一张（研究票除外），产出决策不是交付物；雾散后进 /to-spec。只能人启动（disable-model-invocation: true + allow_implicit_invocation: false）。

何时伸手 / 何时换

伸手：全新产品、巨大功能；方向隐约有，从这里到终点的路看不见，连第一张工单都列不出。
大但已清楚 → to-spec；模糊但一个会话装得下 → grill-with-docs；计划懂了要切片 → to-tickets。
别人提的原始 issue → triage；有东西坏了 → diagnosing-bugs；拿不准 → ask-matt。
前置：setup 跑过（docs/agents/issue-tracker.md 有 Wayfinding operations 一节）；没有 tracker 配置 → 退回本地 markdown 约定。
ask-matt 警告：slower and denser，只留给真大而雾的事，well-scoped feature 别用。

词汇表

Destination（目的地）: 地图要找的终点：一份 spec、一个要拍板的决策，或一次就地变更。画图第一个动作就是命名它——它定死范围，每张票拿它来量。一两行就够。
Map（地图）: 挂 wayfinder:map 标签的单个 issue，唯一权威工件。索引不是仓库：决策只住在票里，地图只写一行摘要加链接。
Decision ticket（决策票）: 地图的子 issue，正文只有一个问题；解决产物是决策，不是构建切片（CONTEXT.md 收录词）。挂 wayfinder:<type> 标签，按一个 100K token 会话的体量切。
Frontier（前线）: 开放 + 无阻塞 + 未认领的子票集合——现在就能上手的工作面。靠原生阻塞关系画在工单系统自己的界面里。
Fog of war（战争迷雾）: 知道会来、但还没法精确写成问题的决策，记在地图 Not yet specified 一节。雾只朝目的地聚集。
Graduation（毕业）: 解决一张票 → 清掉它前方的雾 → 能写清的部分开成新票 → 从 Not yet specified 划掉，只以票的形式存在。
Resolution comment（解决评论）: 答案发成票上的一条评论 → 关票 → 地图 Decisions so far 追加一行指针。答案不进票正文；资产链接不粘贴。
HITL / AFK: HITL = 必须和真人实时交流解决（agent 自问自答即违规）；AFK = agent 独自驱动。每张票必居其一。
Claim（认领）: 开工前把票指派给驱动者——assignee 就是认领，是会话的第一笔写入；开放且未指派 = 未认领。

地图身体（五节，开放票不列入）

## Destination        终点，一两行；每个会话开工前先对齐
## Notes              领域 + 每会话该查的 skill + 长期偏好；唯一能推翻 Plan-don't-do 的入口
## Decisions so far   已关票一行一条：名字包链接 + 一行 gist，绝不复述
## Not yet specified  雾：在范围内但还不锋利的疑似问题
## Out of scope       判出这次努力的活：关闭票 + 一行理由，永不毕业

Refer by name：人读的叙述里票用标题指代、名字包住链接；不许裸 #42, #43 墙。

四种票型

票型	HITL/AFK	解决器	选它的时机
`research`	AFK	`/research` 子代理，发现落一次性 `research/<name>` 分支	需要当前目录之外的事实（文档、API、知识库）
`prototype`	HITL	`/prototype` 或大纲/粗稿/stub	关键问题是「该长什么样、该怎么表现」
`grilling`	HITL	`/grilling` + `/domain-modeling`，一次一个问题	默认票型，拿不准就是它
`task`	HITL 或 AFK	手动劳动；agent 能做就独自做，否则给人精确清单	没的可决定/原型/研究，但讨论被一件体力活挡着（注册服务、开权限、搬数据）

Plan, don't do：task 是唯一「做」的票型，资格是「解锁一个决策，不是交付目的地」；整纪律只能被这次努力的 Notes 一节推翻。

两种调用模式

画图（带松散想法 /wayfinder）：
  1 命名目的地（grilling + domain-modeling）
  2 广度优先再 grill 一轮 → 没翻出雾 = 不需要地图，停下问用户
  3 建 wayfinder:map issue（Destination/Notes 填好，雾进 Not yet specified）
  4 开能写清的票 → 第二遍再接阻塞边（先要有 id）
  5 每张 research 票派一个并行子代理
  6 停——画图就是一个会话的全部，不亲手解决任何票

走票（带地图 URL/编号 /wayfinder，票可不带）：
  1 载地图低分辨率视图
  2 选票（用户点名 > 前线第一张）→ 先认领再开工
  3 解决：按需 zoom 拉票正文；调 Notes 点名的 skill；拿不准就 grilling + domain-modeling
  4 记录：解决评论 → 关票 → 地图 Decisions so far 追加指针
  5 维护：新票先建后接；雾毕业并划掉；越界票关掉留行进 Out of scope；被推翻的票更新或删

铁律：一个会话最多解决一张票——research 票是唯一例外。
并发是常态：认领必须是会话的第一笔写入。

雾 vs 票 vs 范围之外

判定只看一点：现在能否精确陈述问题，不是能否回答。能 → 开票（哪怕被阻塞）；不能 → 留雾。
别把雾预切成票：雾比票粗，一块雾可能毕业成几张，也可能一张不剩。
越过目的地 = Out of scope：不是雾，永不毕业；重画目的地才回来，且算新努力。
别和 triage 的 .out-of-scope/ 目录混：一个是地图正文小节，一个是分拣归档目录。

会改什么

动作	写哪
画图	1 个 `wayfinder:map` issue + N 个子 issue + 阻塞边（本地：`.scratch/<effort>/map.md` + `issues/NN-*.md`）
研究子代理	一次性 `research/<name>` 分支 + 票上上下文指针
认领	票的 assignee（本地：`Status: claimed`）——第一笔写入
解决	解决评论 + 关票 + Decisions so far 指针 + 划雾 + 新票接线（本地：`## Answer` + `Status: resolved`）
grilling 过程中	CONTEXT.md / ADR 可能被 domain-modeling 更新——不是 wayfinder 自己写
业务代码	默认什么都不写（Plan, don't do；Notes 可推翻）

下一步

默认：/to-spec——把地图链着的决策折叠成可建计划 → /to-tickets → /implement。
例外：努力真的变小了才直接 /implement；否则跳过折叠 = 扔掉链着的细节（ask-matt 明令警告）。
画图时发现没雾：地图不建，直接按用户选择进主流程。

微调入口（症状 → 改哪段）

症状	先查
一会话解决多张票 / 画图当天顺手解决票	SKILL.md Invocation 开头铁律 + Chart 第 6 步
grilling 票上 agent 自问自答	SKILL.md Ticket Types 开头 HITL 段（别改 grilling skill）
雾被预切成小票	Fog of war 的「Fog or ticket?」判定
越界票留在前线 / 进了 Decisions so far	Out of scope 一节：关掉 + 留行 + 不进已决清单
裸编号墙 `#42, #43`	Refer by name 一节
认领/阻塞/前线查询的物理操作不对	该仓库 `docs/agents/issue-tracker.md` 的 Wayfinding operations；模板源在 setup skill 的三份 issue-tracker-*.md（别改 wayfinder/SKILL.md——它只写语义）
答案回填进票正文 / 资产全文粘贴	The Map / Tickets：答案不进正文，资产用链接
想让 AI 自动启用它	设计如此；要改得同时翻 frontmatter 的 disable-model-invocation 与 openai.yaml 的 allow_implicit_invocation

tracker 物理操作一行版

GitHub：gh issue create --label wayfinder:map；子票 = sub-issue（退化：Part of #<map> + 任务清单）；
        阻塞 = 原生依赖 blocked_by（用数据库 .id 不是 #number）；认领 gh issue edit --add-assignee @me
GitLab：glab issue create --label wayfinder:map；子票顶部 Part of #<map>；阻塞 = /blocked_by note
        （Premium 功能，免费档退化 Blocked by 行）；认领 glab issue update --assignee @me；
        注意 close 不带评论，先 note 后 close
本地： map.md + issues/NN-*.md；Blocked by: NN 行；Status: claimed/resolved；答案进 ## Answer