分诊

将项目问题跟踪器上的 issue 通过一个小状态机进行分诊角色流转。

如果本仓库将外部拉取请求视为请求入口（参见 issue-tracker 配置），分诊也涵盖它们：PR 是附带代码的 issue，使用相同角色、相同状态和相同状态机，只是下面标记为 “for a PR” 的几处有差异。按跟踪器配置将单独的 #42 解析为 issue 或 PR。

分诊期间发布到问题跟踪器的每条评论或每个 issue 必须以以下免责声明开头：

> *This was generated by AI during triage.*

参考文档

• [AGENT-BRIEF.md](AGENT-BRIEF.md)：如何编写持久的代理简报
• [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)：.out-of-scope/ 知识库如何工作

角色

两个类别角色：

• bug：某处已损坏
• enhancement：新功能或改进

五个状态角色：

• needs-triage：维护者需要评估
• needs-info：等待报告者提供更多信息
• ready-for-agent：规格完整，可交给 AFK 代理
• ready-for-human：需要人工实现
• wontfix：不会处理

对于 PR，相同状态需结合附带的代码理解：ready-for-agent 表示已附带简报，代理应对 diff 采取下一步；ready-for-human 表示可以由人工合并。

每个已分诊 issue 应恰好带有一个类别角色和一个状态角色。如果状态角色冲突，标记出来并先询问维护者，再做其他任何事。

这些是规范角色名称。问题跟踪器中实际使用的标签字符串可能不同。映射应已提供给你。如果没有，请告诉用户运行 /setup-matt-pocock-skills。

状态转换：未标记的 issue 通常先进入 needs-triage；之后可转为 needs-info、ready-for-agent、ready-for-human 或 wontfix。needs-info 在报告者回复后返回 needs-triage。维护者可以随时覆盖；标记看起来异常的转换，并在继续前询问。

调用

维护者调用 /triage 并用自然语言描述他们想要什么。解释请求并行动。示例：

• “给我看任何需要我关注的内容”
• “我们看看 #42”（issue 或 PR）
• “将 #42 移到 ready-for-agent”
• “有哪些已准备好让代理接手？”

展示需要关注的内容

查询问题跟踪器，并按最旧优先展示三个类别：

1. 未标记：从未分诊。
2. needs-triage：评估进行中。
3. 自上次分诊记录以来有报告者活动的 needs-info：需要重新评估。

当 PR 在范围内时，将这些外部 PR 包含在这些类别中，并在每行标记 [PR] 或 [issue]。发现仅显示*外部* PR（跟踪器配置定义谁算外部），因此协作者正在进行的 PR 不是分诊工作。此过滤仅用于发现；明确命名的 PR 无论作者是谁都会被分诊。

显示每个项目的计数和一行摘要。让维护者选择。

分诊特定 issue 或 PR

1. 收集上下文。 阅读完整 issue 或 PR（正文、评论、标签、作者、日期；对于 PR，还包括 diff）。解析任何先前的分诊记录，以免重新询问已解决的问题。使用项目的领域术语表探索代码库，并遵守该区域的 ADRs。针对代码库运行两项检查：(a) 冗余：按领域概念（而不只是请求的措辞）搜索所请求行为的现有实现，并报告你查看过的位置。如果找到，这就是已实现的 wontfix（步骤 5）。(b) 先前拒绝：读取 .out-of-scope/*.md，并指出任何与此请求相似的条目。

1. 给出建议。 告诉维护者你的类别和状态建议及理由，加上与请求相关的简短代码库摘要（包括是否已实现）。等待指示。

1. 验证主张。 在任何质询之前，检查主张是否成立。对于 bug，根据报告者的步骤复现。对于 PR，确认 diff 做到了它声称的事情：检出它，运行相关测试或命令。报告发生了什么：已确认（带代码路径）、失败，或细节不足（强烈的 needs-info 信号）。已确认的验证会使代理简报强得多。

1. 质询（如需要）。 如果请求需要充实，调用 Skill 工具两次，分别用于 “grilling” 和 “domain-modeling”，通过一轮轮提问把它质询到成型，提炼领域术语，并在决策确定时同步更新 CONTEXT.md/ADRs。

1. 应用结果：

• ready-for-agent：发布代理简报评论（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
• ready-for-human：与代理简报结构相同，但说明为何不能委派（判断、外部访问、设计决策、手动测试）。
• needs-info：发布分诊记录（模板见下）。
• 对于 wontfix，关闭 issue，评论内容取决于*原因*：
• 已实现：该更改已存在于代码库中。指出它所在的位置；不要写入 .out-of-scope/（该知识库用于*被拒绝*的请求，而不是已构建的请求）。
• 被拒绝（bug）：给出礼貌的解释，然后关闭。
• 被拒绝（enhancement）：写入 .out-of-scope/，在评论中链接它，然后关闭（[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
• needs-triage：应用该角色。如有部分进展，可选地发表评论。

快速状态覆盖

如果维护者说“将 #42 移到 ready-for-agent”，信任他们并直接应用该角色。确认你即将做什么（角色变更、评论、关闭），然后行动。跳过质询。如果在没有质询会话的情况下移到 ready-for-agent，询问他们是否想撰写代理简报。

Needs-info 模板

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

将质询期间解决的所有内容记录在“established so far”下，以免工作丢失。问题必须具体且可操作，而不是“请提供更多信息”。

恢复之前的会话

如果 issue 或 PR 上存在先前的分诊记录，阅读它们，检查报告者是否已回答任何未决问题，并在继续之前呈现更新后的全貌。不要重新询问已解决的问题。