Agent Skills 工程化实践 09：triage、spec、tickets 与 wayfinder 不是同一层计划

先分清四种不同的不确定性

这四个 Skills 都会产生 issue 或 Markdown，很容易被误认为不同口味的 task management。其实它们处理的是四种不同状态：

• triage：外部请求是否真实、完整、值得进入队列？
• to-spec：我们已经讨论清楚的内容，究竟决定了什么？
• to-tickets：如何把一份计划切成可独立验证、依赖明确的工作？
• wayfinder：如果连路线都看不见，哪些 decisions 必须先被解决？

顺序不是固定流水线。一个 incoming bug 可以从 triage 进入 diagnosis；一个已经对齐的小 change 可以直接从 conversation 进入 implement；只有跨多个 session 的 build 才值得承担 spec 与 tickets 的成本。

triage：管理 request surface

触发方式：User-invoked。 在完成 repo setup 后运行：

/triage #42

它把 issues 与外部 PRs 放进一个 role state machine：categorise、verify、补充信息、形成 agent-ready brief，或明确拒绝。外部 PR 被视为“带着代码的 issue”，仍要先确认其意图和可验证性。

它与 /to-tickets 的根本区别是来源：triage 面向别人提交到你的 request surface；to-tickets 面向团队已经讨论过、主动生成的 work。后者默认 ready-for-agent，再次 triage 只会让任务在流程中绕圈。

使用边界： 运行前确认 docs/agents/issue-tracker.md 与 label mapping 存在，而且 tracker 中真的创建了对应 labels。Skill 写映射，不负责替你创建 labels。它向 tracker 写入的 AI triage 评论必须带免责声明。

上游 Skill：triage

to-spec：把已经发生的讨论压成决定

触发方式：User-invoked。 它不重新 interview：

/to-spec

调用前应该已经通过 conversation 或 grill-with-docs 对齐。它会探索当前 codebase，用 domain glossary 写 spec，并与你确认 testing seams。输出发布到已配置的 issue tracker。

好的 spec 说明用户问题、solution、user stories、implementation decisions、testing decisions、out of scope 和未解决 notes。它描述 module、interface、schema 与 contract，不把今天的文件路径误当成长期设计。

常见误用： 在分歧仍存在时调用，然后期待 Skill 自行补齐产品决定；或者把 spec 写成待改文件清单。前者制造伪共识，后者让文档在第一次重构后立即失真。

上游 Skill：to-spec

to-tickets：用 tracer bullets 形成执行 frontier

触发方式：User-invoked。 可以接 spec、plan、issue URL，也可以接当前 conversation：

/to-tickets docs/specs/export-jobs.md

每张 ticket 应该是一条窄但完整的 vertical slice，能独立 demo 或验证。横向拆成“数据库 ticket、API ticket、UI ticket、测试 ticket”会把反馈推迟到最后；tracer bullet 则尽早穿透所需层级，证明真实用户路径成立。

每张 ticket 还要声明 Blocked by。没有 blocker 的 tickets 构成当前 execution frontier；依赖尚未确定 contract 的 ticket 不能因为“Agent 有空”就提前开始。使用真实 tracker 时，优先使用原生 blocking links；使用 local markdown 时，把 edges 明文写进文件。

完成标准： fresh session 只读一张 ticket 就能知道上下文、acceptance criteria、验证方法和依赖；票据顺序反映 blockers-first，而不是作者想到它们的顺序。

上游 Skill：to-tickets

wayfinder：规划 decisions，不是提前做 implementation

触发方式：User-invoked。 当 effort 大到一个 session 装不下，而且 destination 与路线都仍在 fog 中：

/wayfinder 把单租户系统迁移为多租户，同时保持现有客户不停机

它会在 issue tracker 上创建一张 shared map，再建立 decision tickets。每张 ticket 的产物是一个决定，而不是一段 build；地图完成的标准是“去 destination 的路已经清楚”，不是“destination 已经被交付”。

decision ticket 可以调用 Research、Prototype 或 Grilling 来消除不同类型的不确定性。地图中的人类可读内容用 ticket name，而不是一墙 #42 #43；resolved decisions 回写到 map，成为后续 tickets 的可靠前提。

什么时候不要用： 一个 session 可以讨论清楚的小功能；已有清晰 spec 只差拆票；或者你只是想用更多 planning 让任务显得正式。Wayfinder 的成本只在真实 fog of war 中成立。

上游 Skill：wayfinder

一张选择表

当前状态	正确入口	主要产物
别人提交了 bug、request 或 PR	/triage	verified request / agent-ready brief / rejection
conversation 已经形成共识	/to-spec	决策化 spec
plan 已清楚，需要多个执行单元	/to-tickets	tracer-bullet tickets + blocking edges
effort 跨多 session，路线仍模糊	/wayfinder	shared decision map

规划的价值不在文档数量，而在减少错误开工。每个 artifact 都应该回答一个不同问题；如果四种文档只是换标题重复同一段背景，它们就没有形成真正的 phase boundary。

来源与版本

• 上游参考：README Reference
• 参考分支：main · 核验 commit：8b78b53 · 核验日期：2026-08-14