triage
让工单和外部 PR 在一套分诊角色的状态机中流转——分类、验证、必要时拷问,并写出可供 agent 处理的简报。
- License 许可
- MIT
- 最近更新
- 2026-08-13
- Stars
- ★ 31
- Forks
- 6
01 前言 Front Matter
- name
- triage
- description
- 让工单和外部 PR 在一套分诊角色的状态机中流转——分类、验证、必要时拷问,并写出可供 agent 处理的简报。
- disable-model-invocation
- true
02 资源文件 3
- 参考文档AGENT-BRIEF.md7.4 KB
- 参考文档agents/openai.yaml136 B
- 参考文档OUT-OF-SCOPE.md4.4 KB
03 SKILL.md 正文
分诊
让项目工单跟踪器上的工单在一个小型分诊角色状态机中流转。
如果这个仓库把外部 pull request 当作请求入口(见工单跟踪器配置),分诊也覆盖它们:一个 PR 就是一个附带代码的工单——同样的角色、同样的状态、同样的状态机,只有下面标了「对于 PR」的几处差异。按跟踪器配置把一个裸的 #42 解析为一个 issue 或 PR。
分诊期间发布到工单跟踪器的每一条评论或工单都必须以这条免责声明开头:
> *This was generated by AI during triage.*
参考文档
- AGENT-BRIEF.md — 如何写出经久耐用的 agent 简报
- 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 意思是简报已附上、一个 agent 应该在这个 diff 上迈出下一步;ready-for-human 意思是它已准备好由人类来合并。
每个被分诊的工单都应恰好携带一个分类角色和一个状态角色。如果状态角色相冲突,先标记出来并询问维护者,然后再做任何其他事。
这些是规范的角色名——工单跟踪器里实际使用的标签字符串可能不同。这个映射应当已经提供给你——如果没有,运行 /setup-matt-pocock-skills。
状态转换:一个未打标签的工单通常先进入 needs-triage;从那里它移动到 needs-info、ready-for-agent、ready-for-human 或 wontfix。needs-info 在报告者回复后返回 needs-triage。维护者可以随时覆盖——标记出看起来不寻常的转换并在继续前询问。
调用
维护者调用 /triage 并用自然语言描述他们想要什么。解读请求并行动。示例:
- 「给我看任何需要我关注的东西」
- 「我们来看看 #42」(issue 或 PR)
- 「把 #42 移到 ready-for-agent」
- 「有什么是准备好给 agent 领取的?」
展示需要关注的东西
查询工单跟踪器并呈现三个桶,最旧的在前:
- 未打标签 — 从未分诊过。
needs-triage— 评估进行中。needs-info且自上次分诊笔记以来报告者有活动的 — 需要重新评估。
当 PR 在范围内时,把外部 PR 也纳入这些桶,并给每一行打上 [PR] 或 [issue] 标记。发现只浮现外部 PR(跟踪器配置定义了谁算外部)——一个协作者进行中的 PR 不是分诊工作。这个过滤器只用于发现;一个被明确点名的 PR 不论作者是谁都始终会被分诊。
展示计数和每项一行的摘要。让维护者挑选。
分诊一个具体的 issue 或 PR
-
收集上下文。 读完整的 issue 或 PR(正文、评论、标签、作者、日期;对于 PR,还有 diff)。解析任何先前的分诊笔记,这样你不会重新问已解决的问题。用项目的领域词汇表探索代码库,尊重该区域里的 ADR。对代码库做两项检查:(a) 冗余——按领域概念(不只是请求的措辞)搜索所请求行为的现有实现,并报告你查过哪里。如果找到,那就是一个已实现的
wontfix(第 5 步)。(b) 先前的拒绝——读.out-of-scope/*.md并浮现任何与这个请求相似的。 -
推荐。 带上你的理由,把你的分类和状态推荐告诉维护者,外加一段与请求相关的简短代码库摘要——包括它是否已经实现。等待指示。
-
验证声称。 在任何拷问之前,检查这个声称是否站得住脚。对于一个 bug,从报告者的步骤复现它。对于一个 PR,确认 diff 做了它声称的事——check out 它,运行相关的测试或命令。报告发生了什么:已确认(附代码路径)、失败,或细节不足(一个强烈的
needs-info信号)。一次已确认的验证会造就一份强得多的 agent 简报。 -
拷问(如需)。 如果请求需要充实,就一起运行
/grilling和/domain-modeling技能——一次一轮问题地把它拷问成型,磨锐领域术语,并在决策落地时就地更新CONTEXT.md/ADR。 -
应用结果:
ready-for-agent— 发一条 agent 简报评论(AGENT-BRIEF.md)。ready-for-human— 与 agent 简报同样的结构,但注明为什么它不能被委派(判断题、外部访问、设计决策、手动测试)。needs-info— 发分诊笔记(模板见下)。wontfix— 关闭,评论内容取决于为什么:- 已实现 — 这个改动在代码库里已经存在。指出它在哪里;不要写到
.out-of-scope/(那个知识库是给被拒绝的请求的,不是给已构建的)。 - 被拒绝(bug) — 礼貌解释,然后关闭。
- 被拒绝(enhancement) — 写到
.out-of-scope/,从一条评论链接到它,然后关闭(OUT-OF-SCOPE.md)。
- 已实现 — 这个改动在代码库里已经存在。指出它在哪里;不要写到
needs-triage— 应用这个角色。如果有部分进展,可选地加一条评论。
快速状态覆盖
如果维护者说「把 #42 移到 ready-for-agent」,信任他们并直接应用这个角色。确认你即将做什么(角色变更、评论、关闭),然后行动。跳过拷问。如果在没有拷问会话的情况下移到 ready-for-agent,问一句他们是否想写一份 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 上存在先前的分诊笔记,读它们,检查报告者是否回答了任何悬而未决的问题,并在继续前呈现一幅更新后的图景。不要重新问已解决的问题。
04 同仓库更多 Skills
writing-for-agents
为智能体撰写文档。当创建或编辑技能,或修改 AGENTS.md 或 CLAUDE.md 时使用。
wait-what
停一下。那最后一条消息没能领会——重新表述它。
to-questionnaire
把一个你无法完全回答的决策变成一份问卷,交给别人填写。
teach
在本工作区内向用户传授一项新技能或概念。
handoff
把当前对话压缩成一份交接文档,供另一个 agent 接手。
grilling
就一个计划、决定或想法不留情面地拷问用户。当用户想对自己的思考做压力测试,或使用任何 'grill' 触发短语时使用。