Back to Details

triage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Triage

问题分诊（Triage）

Move issues on the project issue tracker through a small state machine of triage roles.
If this repo treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: a PR is an issue with attached code — same roles, same states, same machine, with a few deltas marked "for a PR" below. Resolve a bare 
#42
to an issue or PR per the tracker config.
Every comment or issue posted to the issue tracker during triage must start with this disclaimer:
> *This was generated by AI during triage.*
通过一套小型的分诊（Triage）角色状态机来处理项目问题追踪器中的问题。
如果本仓库将外部Pull Request（PR）视为需求入口（请查看问题追踪器配置），那么分诊流程也适用于它们：PR是附带代码的问题——适用相同的角色、相同的状态、相同的状态机，仅在下文标记为“针对PR”的部分存在少量差异。根据追踪器配置，将纯数字编号
#42
解析为对应的问题或PR。
分诊期间在问题追踪器上发布的每条评论或问题必须以以下免责声明开头：
> *This was generated by AI during triage.*

Reference docs

参考文档

  • AGENT-BRIEF.md — how to write durable agent briefs
  • OUT-OF-SCOPE.md — how the 
    .out-of-scope/
    knowledge base works
  • AGENT-BRIEF.md — 如何撰写可长期使用的Agent任务简报
  • OUT-OF-SCOPE.md — 
    .out-of-scope/
    知识库的运作方式

Roles

角色

Two category roles:
  • bug
    — something is broken
  • enhancement
    — new feature or improvement
Five state roles:
  • needs-triage
    — maintainer needs to evaluate
  • needs-info
    — waiting on reporter for more information
  • ready-for-agent
    — fully specified, ready for an AFK agent
  • ready-for-human
    — needs human implementation
  • wontfix
    — will not be actioned
For a PR, the same states read against the attached code: 
ready-for-agent
means a brief is attached and an agent should take the next step on the diff; 
ready-for-human
means it's ready for a human to merge.
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run 
$setup-matt-pocock-skills
if not.
State transitions: an unlabeled issue normally goes to 
needs-triage
first; from there it moves to 
needs-info
, 
ready-for-agent
, 
ready-for-human
, or 
wontfix
. 
needs-info
returns to 
needs-triage
once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
两类分类角色：
  • bug
    — 功能出现故障
  • enhancement
    — 新功能或改进
五类状态角色：
  • needs-triage
    — 等待维护人员评估
  • needs-info
    — 等待提交者提供更多信息
  • ready-for-agent
    — 需求已明确，可交由离线（AFK）Agent处理
  • ready-for-human
    — 需要人工实现
  • wontfix
    — 不会采取任何行动
对于PR，这些状态针对附带的代码解读：
ready-for-agent
表示已附上任务简报，Agent应针对代码差异执行下一步操作；
ready-for-human
表示已准备好由人工合并。
每个经过分诊的问题应恰好带有一个分类角色和一个状态角色。如果状态角色存在冲突，请先标记并询问维护人员，再进行其他操作。
这些是标准角色名称——问题追踪器中使用的实际标签字符串可能有所不同。应该已向你提供了映射关系，若未提供，请运行
$setup-matt-pocock-skills
。
状态流转：未标记的问题通常首先进入
needs-triage
状态；之后可流转至
needs-info
、
ready-for-agent
、
ready-for-human
或
wontfix
状态。当提交者回复后，
needs-info
状态将转回
needs-triage
状态。维护人员可随时覆盖流转规则——若发现异常流转，请先标记并询问，再继续操作。

Invocation

调用方式

The maintainer invokes 
$triage
and describes what they want in natural language. Interpret the request and act. Examples:
  • "Show me anything that needs my attention"
  • "Let's look at #42" (issue or PR)
  • "Move #42 to ready-for-agent"
  • "What's ready for agents to pick up?"
维护人员通过调用
$triage
并以自然语言描述需求。解读请求并执行操作。示例：
  • "展示所有需要我关注的内容"
  • "查看#42"（问题或PR）
  • "将#42转移至ready-for-agent状态"
  • "哪些内容已准备好交由Agent处理？"

Show what needs attention

展示需关注的内容

Query the issue tracker and present three buckets, oldest first:
  1. Unlabeled — never triaged.
  2. needs-triage
     — evaluation in progress.
  3. needs-info
    with reporter activity since the last triage notes     — needs re-evaluation.
When PRs are in scope, include external PRs in these buckets and tag each line 
[PR]
or 
[issue]
. Discovery surfaces only external PRs (the tracker config defines who counts as external) — a collaborator's in-flight PR is not triage work. This filter is discovery-only; an explicitly named PR is always triaged regardless of author.
Show counts and a one-line summary per item. Let the maintainer pick.
查询问题追踪器，并按创建时间从早到晚展示三类内容：
  1. 未标记 — 从未经过分诊处理。
  2. needs-triage
     — 评估正在进行中。
  3. needs-info
    且自上次分诊记录后提交者有活动     — 需要重新评估。
若PR在处理范围内，将外部PR纳入上述类别，并在每一行标记
[PR]
或
[issue]
。仅展示外部PR（追踪器配置定义了外部人员的范围）——协作者正在处理的PR不属于分诊工作范畴。此筛选仅适用于自动发现；若明确指定某个PR，无论作者是谁，都需进行分诊处理。
展示每类内容的数量，并为每个条目提供一行摘要。由维护人员选择处理对象。

Triage a specific issue or PR

分诊特定问题或PR

  1. Gather context. Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) redundancy — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented 
    wontfix
    (step 5). (b) prior rejection — read 
    .out-of-scope/*.md
    and surface any that resembles this request.
  2. Recommend. Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request — including whether it's already implemented. Wait for direction.
  3. Verify the claim. Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong 
    needs-info
    signal). A confirmed verification makes a much stronger agent brief.
  4. Grill (if needed). If the request needs fleshing out, run the 
    $grilling
    and 
    $domain-modeling
    skills together — grill it into shape one question at a time, sharpening domain terms and updating 
    CONTEXT.md
    /ADRs inline as decisions land.
  5. Apply the outcome:
    • ready-for-agent
      — post an agent brief comment (AGENT-BRIEF.md).
    • ready-for-human
      — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
    • needs-info
      — post triage notes (template below).
    • wontfix
      — close, with the comment depending on why:
      • Already implemented — the change already exists in the codebase. Point to where it lives; do not write to 
        .out-of-scope/
        (that KB is for rejected requests, not built ones).
      • Rejected (bug) — polite explanation, then close.
      • Rejected (enhancement) — write to 
        .out-of-scope/
        , link to it from a comment, then close (OUT-OF-SCOPE.md).
    • needs-triage
      — apply the role. Optional comment if there's partial progress.
  1. 收集上下文信息。完整阅读问题或PR（包括正文、评论、标签、作者、日期；对于PR，还需查看代码差异）。解析之前的分诊记录，避免重复询问已解决的问题。利用项目领域术语表探索代码库，遵循该领域的架构决策记录（ADR）。对代码库进行两项检查：(a) 冗余性检查——根据领域概念（而非仅根据请求的措辞）搜索是否已有请求功能的实现，并报告搜索范围。若找到，则标记为已实现的
    wontfix
    （步骤5）。(b) 历史拒绝记录检查——阅读
    .out-of-scope/*.md
    文件，找出与当前请求类似的记录。
  2. 给出建议。向维护人员说明你推荐的分类和状态及理由，同时提供与请求相关的代码库简要摘要——包括是否已实现该功能。等待指示。
  3. 验证诉求。在深入询问之前，先验证诉求是否成立。对于bug问题，按照提交者提供的步骤复现问题。对于PR，确认代码差异是否实现了其声称的功能——检出代码，运行相关测试或命令。报告验证结果：已确认（附带代码路径）、复现失败，或细节不足（强烈的
    needs-info
    信号）。经过确认的验证能让Agent任务简报更具说服力。
  4. 深入询问（如有必要）。如果需求需要进一步完善，同时调用
    $grilling
    和
    $domain-modeling
    技能——逐个提出问题来明确需求，细化领域术语，并在决策确定后实时更新
    CONTEXT.md
    /ADRs。
  5. 应用处理结果：
    • ready-for-agent
      — 发布Agent任务简报评论（参考AGENT-BRIEF.md）。
    • ready-for-human
      — 采用与Agent任务简报相同的结构，但需注明无法委托给Agent的原因（如需要主观判断、外部访问权限、设计决策、手动测试等）。
    • needs-info
      — 发布分诊记录（模板如下）。
    • wontfix
      — 关闭问题，评论内容取决于原因：
      • 已实现——该变更已存在于代码库中。指出其所在位置；请勿写入
        .out-of-scope/
        目录（该知识库用于存放被拒绝的请求，而非已实现的功能）。
      • 拒绝（bug）——礼貌地说明原因，然后关闭问题。
      • 拒绝（enhancement）——写入
        .out-of-scope/
        目录，在评论中链接至该文件，然后关闭问题（参考OUT-OF-SCOPE.md）。
    • needs-triage
      — 应用该角色标签。若有部分进展，可选择性添加评论。

Quick state override

快速状态覆盖

If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to 
ready-for-agent
without a grilling session, ask whether they want to write an agent brief.
如果维护人员说“将#42转移至ready-for-agent状态”，请直接执行该操作。先确认你即将执行的操作（角色变更、评论、关闭问题），然后再行动。跳过深入询问步骤。若未经过深入询问就将状态改为
ready-for-agent
，请询问维护人员是否需要撰写Agent任务简报。

Needs-info template

待补充信息模板

markdown
undefined
markdown
undefined

Triage Notes

Triage Notes

What we've established so far:
  • point 1
  • point 2
What we still need from you (@reporter):
  • question 1
  • question 2

Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
What we've established so far:
  • point 1
  • point 2
What we still need from you (@reporter):
  • question 1
  • question 2

将深入询问过程中已解决的所有内容记录在“已明确事项”部分，避免工作成果丢失。提出的问题必须具体且可执行，不能是“请提供更多信息”这类模糊表述。

Resuming a previous session

恢复之前的分诊会话

If prior triage notes exist on the issue or PR, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
如果问题或PR上已有之前的分诊记录，请先阅读这些记录，检查提交者是否已回答未解决的问题，并在继续之前展示最新情况。请勿重复询问已解决的问题。