Triage

Triage（分类）

术语约定： 以下关键术语保持固定译法，含英文源词以便对照：

English	中文
triage	triage
role	角色
state machine	状态机
agent brief	agent brief
grilling	grilling
maintainer	维护者
reporter	报告人
AFK agent	AFK agent
out of scope	超出范围

将项目 issue tracker 上的 issue 通过一个小型状态机进行 triage 流转。

如果本仓库将外部 PR 作为请求面处理（见 issue-tracker 配置），triage 同样覆盖它们：PR 是带有代码的 issue —— 相同的角色、相同的状态、相同的机器，只是下面标注了一些"针对 PR"的差异。将裸 #42 解析为 issue 或 PR，按 tracker 配置处理。

Triage 期间发布到 issue tracker 的每条评论必须以如下声明开头：

> *本文由 AI 在 triage 期间生成。*

参考文档

• AGENT-BRIEF.md —— 如何编写持久的 agent brief
• OUT-OF-SCOPE.md —— .out-of-scope/ 知识库的工作原理

角色

两个分类角色：

• bug —— 有东西坏了
• enhancement —— 新功能或改进

五个状态角色：

• needs-triage —— 维护者需要评估
• needs-info —— 等待报告人提供更多信息
• ready-for-agent —— 完全明确，准备好让 AFK agent 接取
• ready-for-human —— 需要人类实现
• wontfix —— 不会处理

对于 PR，相同的状态适用于附带的代码：ready-for-agent 表示已附加 brief，agent 应该在 diff 上执行下一步；ready-for-human 表示准备好让人合并。

每个 triage 后的 issue 应恰好携带一个分类角色和一个状态角色。如果状态角色冲突，标注出来并在做任何其他事情前询问维护者。

这些是规范的角色名称——issue tracker 中实际使用的标签字符串可能不同。映射关系应该已经提供给你——如果没有，运行 /setup-rolex-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"
• "哪些准备好了让 agent 接取？"

显示需要关注的内容

查询 issue tracker 并按三个桶展示，最早的在最前面：

1. 未标注 —— 从未被 triage 过
2. needs-triage —— 评估进行中
3. needs-info 且报告人在上次 triage 后有活动 —— 需要重新评估

当 PR 在范围内时，将外部 PR 包含在这些桶中，并在每行标注 [PR] 或 [issue]。发现阶段只暴露外部 PR（tracker 配置定义了谁算外部）——协作者进行中的 PR 不是 triage 工作。此过滤器仅适用于发现阶段；明确指定的 PR 无论作者如何都会进行 triage。

显示计数和每项的简要摘要。让维护者选择。

Triage 特定 issue 或 PR

1. 收集上下文。 阅读完整的 issue 或 PR（正文、评论、标签、作者、日期；对于 PR，还有 diff）。解析任何先前的 triage 记录，以免重复提问已解决的问题。使用项目的领域词汇浏览代码库，尊重你正在接触区域的 ADR。针对代码库运行两项检查：（a）冗余——按领域概念搜索请求行为的现有实现（不仅仅是请求的措辞），并报告搜索位置。如果找到，则是已实现的 wontfix（步骤 5）。（b）之前的拒绝——阅读 .out-of-scope/*.md，找出任何与本次请求相似的内容。

2. 推荐。 告诉维护者你的分类和状态建议及其理由，加上与请求相关的简短代码库摘要——包括它是否已实现。等待指示。

3. 验证声明。 在进一步 grilling 之前，检查声明是否成立。对于 bug，按报告人的步骤复现。对于 PR，确认 diff 做了它声称的事情——检出它，运行相关测试或命令。报告发生了什么：验证通过（附代码路径）、失败、或细节不足（强烈的 needs-info 信号）。经过验证的确认能生成更强的 agent brief。

4. Grill（如果需要）。 如果请求需要细化，一起运行 /grilling 和 /domain-modeling skill——一次一个问题地将其打磨成形，同时锐化领域术语，并随着决策落地就地更新 CONTEXT.md/ADR。

5. 应用结果：

   • ready-for-agent —— 发布 agent brief 评论（AGENT-BRIEF.md）。
   • ready-for-human —— 结构与 agent brief 相同，但注明为什么不能委托给 agent（需要判断、外部访问、设计决策、手动测试）。
   • needs-info —— 发布 triage 记录（模板见下）。
   • wontfix —— 关闭，根据原因选择不同评论：
     • 已实现 —— 更改已存在于代码库中。指向所在位置；不要写入 .out-of-scope/（该知识库只针对已拒绝的请求，不是已构建的）。
     • 已拒绝（bug） —— 礼貌解释，然后关闭。
     • 已拒绝（enhancement） —— 写入 .out-of-scope/，在评论中链接，然后关闭（OUT-OF-SCOPE.md）。
   • needs-triage —— 应用角色。如果已有部分进展可加可选评论。

快速状态覆盖

如果维护者说"把 #42 移到 ready-for-agent"，信任他们并直接应用角色。确认你将要做什么（角色更改、评论、关闭），然后执行。跳过 grilling。如果移到 ready-for-agent 但没有 grilling 会话，询问他们是否要写 agent brief。

Needs-info 模板

## Triage Notes

**目前已经确认的情况：**

- 要点 1
- 要点 2

**我们仍然需要你提供的信息（@报告人）：**

- 问题 1
- 问题 2

在"已确认的情况"下捕获 grilling 期间解决的所有内容，以免工作丢失。问题必须具体且可操作，而非"请提供更多信息"。

恢复之前的会话

如果 issue 或 PR 上存在先前的 triage 记录，阅读它们，检查报告人是否已回复任何未解决的问题，然后在继续之前呈现更新的画面。不要重复已解决的问题。