ask-utarn

询问 Utarn

你不可能记住每项技能，所以尽管问。

流程是穿过各项技能的一条路径。大多数路径沿着一条主流程前进，还有两条入口路径会汇入其中。其他内容都是独立技能，或是在底层运行的词汇层。

主流程：从想法到交付

大多数工作都会走这条路线。你有一个想法，希望把它实现出来。

1. /grill-with-docs — 通过访谈打磨想法。只要你在工作目录中工作，就从这里开始：它会保留状态，将学到的内容记录在 CONTEXT.md 和 ADR 中。（没有工作目录？使用 /grill-me — 见“独立技能”。两者都运行相同的 /grilling 基础流程；grill-with-docs 会留下记录，因此只要有仓库可以存放记录，它就是更好的选择。）如果你觉得技术决策应该由 Agent 来做，而不是由你来定，优先使用 /grill-novice：它只会用通俗的简明英语询问功能需求，并在编写任何内容之前总结它的技术假设，让你否决。

2. 分支 — 你能在对话中解决每个问题吗？ 如果问题需要可运行的答案（状态、业务逻辑、必须亲眼查看的 UI），就通过原型绕道，并用 /handoff 双向传递（原型位于自己的目录中，而这正是 /handoff 的用途 — 见“阶段边界”）：

   • 使用 /handoff 移交，然后针对该文件开启一个全新会话，
   • 使用 /prototype 编写临时代码来回答问题，
   • 使用 /handoff 带回你的发现，并在原始想法讨论中引用这些发现。

3. 分支 — 这是一个需要跨多个会话构建的项目吗？

   • 是 → 使用 /to-spec（将讨论整理成规格说明），然后使用 /to-tickets 将其拆分为追踪子弹式工单，每个工单都要声明其阻塞边。使用本地跟踪器时，每个工单对应 .scratch/<feature>/issues/ 下的一个文件，由人工按照先解决阻塞项的顺序处理；使用实际跟踪器时，这些边会转成原生阻塞链接，因此任何阻塞项都已完成的工单都可以领取 — 每个工单都启动一次 /implement，并在每次之间使用 /clear 清理上下文。每个工单都是独立完整的，因此最后一个工单的上下文可以丢弃。
   • 否 → 直接在这里的同一个上下文窗口中运行 /implement。

   无论哪种情况，/implement 都会在内部通过 /tdd 来实现每个问题 — 每次完成一个红绿切片 — 然后在提交之前运行 /code-review，从两个维度（标准 + 规格）审查差异。在不需要完整规格、只想先编写测试再实现某个具体行为时，单独使用 /tdd；想要依据既定基准审查分支或 PR 时，单独使用 /code-review。

上下文管理

步骤 1–3 应始终在同一个不中断的上下文窗口中进行 — 在 /to-tickets 之前不要压缩或清理上下文 — 这样访谈、规格说明和工单都能建立在同一套思路之上。之后，每次 /implement 都从全新上下文开始，根据工单开展工作。

这里的限制是**智能区**：模型仍能清晰推理的窗口范围（当前最先进的模型约为 150k 个 token）。如果会话在到达 /to-tickets 之前就快要超出这个范围，不要在状态变差时硬撑 — 在最近的阶段边界运行 /compact，然后继续（见“阶段边界”）。

切入点

一种引出工作、随后并入主流程的起始情形。

• Bug 和请求堆积如山 → /triage。它会让问题经过各个分诊角色，并产出可供 Agent 处理的问题，之后由 /implement 接手。

  分诊只适用于不是由你创建的问题——Bug 报告、收到的功能请求，以及任何原始提交的问题。/to-tickets 生成的工单已经可以交由 Agent 处理，所以不要对它们进行分诊。

  如果原始报告落在独立的公共问题跟踪仓库中——用户和测试人员针对已发布产品提交问题，而代码位于其他地方——则改用 /bug-tracker 处理该队列（参见 Utarn 专属扩展）。

• 有东西坏了 → /diagnosing-bugs。适用于棘手问题：乍看之下难以发现的 Bug、偶发故障，以及在两个已知正常状态之间悄然引入的回归。它会先要求建立紧密的反馈循环——一条已经能让这个 Bug 触发失败的命令——才开始推测，然后通过回归测试来修复。如果事后分析发现，真正的问题是没有合适的切入点来锁定 Bug，它会转交给 /improve-codebase-architecture。

• 规模庞大、前景模糊的工作——绿地项目或大型功能构建，大到无法在一次会话中完成 → /wayfinder，这里认知负荷最高的工作流。当从当前位置通往目的地的路径尚不清晰时，它会在问题跟踪器上绘制一张包含决策工单的共享地图，并逐一解决——产出的是决策，而不是交付物——直到拨开迷雾、道路清晰。/grill-with-docs 用于打磨能在一次会话中把握的想法；wayfinder 则适用于你无法在一次会话中把握的想法，而且它更慢、更密集，因此只在确实需要时使用，切勿用于范围明确的功能。

  地图清晰后，它会移交，而不会构建：在 /to-spec 处并入主流程，由它将地图中相互关联的决策整合成可执行的计划，然后照常运行 /to-tickets 和 /implement。直接将地图交给 /implement 会跳过整合步骤，丢掉关联细节；只有当工作最终确实很小的时候，才直接进入 /implement。

代码库健康

不是功能开发，而是日常维护。

• /improve-codebase-architecture — 有空时随时运行，让代码库始终适合 Agent 操作。它会发现可深化的机会；选中一个机会后，会生成一个想法，你可以将它带入主流程，在 /grill-with-docs 中继续推进。它负责调查并找出候选项；/codebase-design（见下文）则是你设计所选方案的工作台。

底层术语

两个由模型调用的参考工具，运行在其他技能的底层——各自是对应术语的唯一事实来源。当问题在于用词而非流程时，可直接使用它们；也可以让上面的技能调用它们。

• /domain-modeling — 打磨项目的领域语言：质疑模糊术语，厘清多义词（例如一个“account”承担三种职责），并将难以逆转的决策记录为 ADR。这是 /grill-with-docs 用于保持 CONTEXT.md 成为清晰术语表的主动实践。
• /codebase-design — 用于设计模块形态的深模块术语（模块、接口、深度、切入点、适配器、杠杆、本地性）：在干净的切入点处，通过小接口封装大量行为。/tdd 和 /improve-codebase-architecture 都会使用这套术语。

阶段边界

阶段是一个会话中的一段工作——梳理需求、实现、QA。在两个阶段的边界处，你有五种选择；在整个决策图中，这是最难判断的一项：

• Continue — 留在当前会话。不会产生任何成本，也不会丢失任何内容。
• /clear — 清空上下文窗口，适用于当前内容对接下来的工作毫无用处的情况。
• /handoff — 编写一个可移植的 markdown 文件。适用范围有限：仅用于新的 harness、新的目录、同事，或在阶段进行中分出一项独立任务。它带来的是可移植性。
• Subagent — 将一项范围明确的任务交给自己的上下文窗口，并取回报告。
• /compact — 压缩当前上下文，并用压缩后的内容开启一个新会话。这是默认选项，位于决策树底部，而不是首选。

阅读 PHASE-BOUNDARIES.md，了解按顺序排列的决策树——五个问题、每个分支背后的理由，以及为什么应当最先排除会带来原始来源成本的 Continue。请在边界处做出决定；阶段进行中则继续当前工作，或将剩余任务拆分给子 Agent。

独立技能

完全不属于主流程。

• /grill-me — 与 /grill-with-docs 一样进行不懈的访谈，但无状态：不会在本地保存任何内容，也不会创建 CONTEXT.md。当你不在工作目录中时使用它——打磨计划、设计、文章，或其他不依附于代码仓库的内容。如果你在工作目录中，请改用 /grill-with-docs：它会进行同样的访谈并留下书面记录，因此严格来说更好。
• /grilling — 访谈的基本机制：轮次、前沿问题、事实由 Agent 负责，决策由你来做。/grill-me、/grill-with-docs 和 /grill-novice 是三种命名入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都会在内部运行它。只有当你想不加任何封装地直接进行访谈时，才直接使用它。
• /resolving-merge-conflicts — 逐块处理进行中的合并或变基冲突，依据各方主要来源追溯出的意图来解决，而不是挑选代码行，然后完成操作。它绝不会运行 --abort。它独立于所有流程：当你已经陷入冲突时，就使用它。
• /prototype — 编写一个小型、一次性的程序，用来回答一个设计问题：这个状态模型是否合适，或者这个 UI 应该是什么样子。一次性限制的是代码的编写方式，并不意味着承诺销毁它：得出的结果会融入正式代码，原型本身则会保留为 prototype/<name> 分支上的主要来源，该分支从 main 分出，并在实现 issue 中注明。它是主流程第 2 步中的绕行选项，但只要设计问题难以通过书面方式解决，随时都可以使用。
• /research — 将资料阅读工作委托给后台 Agent：它会针对一个问题调查一手来源，然后在代码仓库中留下带引用的 Markdown 文件。它阅读时，你可以继续工作。它生成的文件是你带入主流程 /grill-with-docs 的材料——研究为思考提供依据，但不能取代思考。
• /to-questionnaire — 当阻碍你的信息不在你脑中或代码库里，而在别人那里时，用它编写一份供对方填写的问卷。它与 /grill-me 的方向相反：它不会围绕主题采访你，而是围绕发送问卷采访你——发给谁、你需要对方提供什么——然后针对信息缺口设计问题。对方的回复可以作为 /grill-with-docs 或 /to-spec 的材料。
• /wizard — 用于只有人类才能完成的步骤：配置基础设施、设置凭据或 CI 密钥、在陌生的第三方控制台中操作，或执行一次性迁移或切换。它会生成一个交互式 bash 脚本，打开每个 URL、收集每个值，并将其写入 .env 和 GitHub secrets——这样你就不必每次都向 Agent 重新解释整个流程。它由用户主动调用，因此只有在人类确实参与其中时才应输入；如果 Agent 可以自行完成，就应该由它来做。它仍属于 in-progress/ 类别，因此不包含在插件中——如果你想使用它，请直接安装。
• /wait-what — 用于纠正没能让对方理解的信息。在对话中途、任何其他技能内部使用它，Agent 就会结合你缺失的上下文，用通俗易懂的语言重新表述刚才的内容，并使用 CONTEXT.md 中的词汇。它可在事后补救；/grill-with-docs 则是事前的解决方案，因为及早商定共同语言，才能避免术语突然冒出来。
• /teach — 使用当前目录作为有状态的工作区，通过多个会话学习一个概念。
• /writing-for-agents — 为 Agent 编写其会使用的文档的参考指南：技能、AGENTS.md 和指向其他文档的文件。

Utarn 专属扩展

这个 fork 保留了一些上游路由器未路由到的技能。它们与主流程技能有所重叠，但仍可用于针对其优化的工作流：

• /to-prd — 类似 /to-spec，但会编写 PRD 格式的文档。为已使用 PRD 这一术语的仓库保留。
• /to-issues 和 /to-issues-yes — 类似 /to-tickets，但会使用垂直切片，将计划、规格说明或 PRD 拆分为可独立领取的问题（而 /to-issues-yes 会直接将它们作为示踪弹问题发布到项目问题跟踪器）。它们是 /to-tickets 的前身；想要使用较早的问题拆分行为时，可以选择它们。
• /to-tickets-yes — /to-tickets 的默认同意变体：生成同样带有阻塞关系的示踪弹工单，但会跳过审批环节，直接发布到配置的跟踪器。拆分流程足够常规、无需来回确认即可放心采用时，可以选择它。
• /to-spec-yes — /to-spec 的默认同意变体：规格说明综合与发布流程相同，但会将提议的边界视为已达成共识，不再向你确认。边界属于常规情况（已有边界，且设置位置符合你的预期）时，可以选择它；规格说明中的 Testing Decisions 部分仍会记录这些边界，因此假设依然清晰可见。
• /setup-utarn-skills-yes — /setup-utarn-skills 的默认值变体：它会根据仓库本身推导所有选项（远程仓库 → 跟踪器、默认分流标签、monorepo 信号 → 文档布局），并且不经确认就写入配置。新仓库的默认值正好符合你的预期时，可以选择它；如果你想对这三项中的任何一项发表意见，或需要 Jira/Linear 等自定义跟踪器，请运行交互式的 /setup-utarn-skills。
• /find-mismatch — 专注于代码审查，查找会在运行时导致错误的问题，并通过 fallow 进行 JS/TS 静态分析。当你只想检测不匹配并进行静态检查，而不需要两个维度的 Standards/Spec 审查时，它是 /code-review 的精简替代方案。
• /work-on-issues — 按顺序获取、实现并关闭 GitHub/GitLab 问题（一次处理一个以 PRD:/feat: 开头的主问题）。它是一个端到端的问题处理工具，封装了已跟踪问题的实现 → 审查 → 关闭循环。
• /bug-tracker 和 /init-bug-tracker — 这对技能用于处理代码不在本地、而是在公共跟踪器中提交的报告。/init-bug-tracker 会创建跟踪器的完整标签分类体系——状态、类型、优先级、验证，以及根据仓库生成的 area:* 标签——为其设置问题表单，并在 ## Agent skills 配置中记录跟踪器。随后，/bug-tracker 会逐个处理可执行队列中的问题：调查并验证带附件的报告、添加标签、标记为进行中、通过隔离的子 Agent 解决问题（类似于 work-on-issues）、将解决摘要发回公共跟踪器，并标记为已解决后关闭。它是 /work-on-issues 和 /triage 在公共跟踪器场景下的对应工具。

前置条件

/setup-utarn-skills — 首次运行工程流程前请先运行它，以配置其他技能所依赖的问题跟踪器、分流标签和文档布局。也支持自定义问题跟踪器。