github-triage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Issue Triage

GitHub Issue 分类处理

Triage issues in the current repo using a label-based state machine. Infer the repo from

git remote

. Use

gh

for all GitHub operations.

使用基于标签的状态机对当前仓库的issues进行分类处理。从

git remote

推断仓库地址，所有GitHub操作均使用

gh

执行。

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/
```
知识库的工作原理

Labels

Label	Type	Description
`bug`	Category	Something is broken
`enhancement`	Category	New feature or improvement
`needs-triage`	State	Maintainer needs to evaluate this issue
`needs-info`	State	Waiting on reporter for more information
`ready-for-agent`	State	Fully specified, ready for AFK agent
`ready-for-human`	State	Requires human implementation
`wontfix`	State	Will not be actioned

Every issue should have exactly one state label and one category label. If an issue has conflicting state labels (e.g. both

needs-triage

and

ready-for-agent

), flag the conflict and ask the maintainer which state is correct before doing anything else. Provide a recommendation.

Label	Type	Description
`bug`	分类标签	某项功能出现故障
`enhancement`	分类标签	新功能或功能改进需求
`needs-triage`	状态标签	维护者需要评估该issue
`needs-info`	状态标签	等待issue提交者提供更多信息
`ready-for-agent`	状态标签	需求已明确，可分配给AFK Agent处理
`ready-for-human`	状态标签	需要人工处理实现
`wontfix`	状态标签	不会对该issue进行任何处理

每个issue必须恰好有一个状态标签和一个分类标签。如果某个issue存在冲突的状态标签（例如同时有

needs-triage

和

ready-for-agent

），请先标记冲突并询问维护者正确的状态后再执行其他操作，同时给出你的处理建议。

State Machine

状态机

Current State	Can transition to	Who triggers it	What happens
`unlabeled`	`needs-triage`	Skill (on first look)	Issue needs maintainer evaluation. Skill applies label after presenting recommendation.
`unlabeled`	`ready-for-agent`	Maintainer (via skill)	Issue is already well-specified and agent-suitable. Skill writes agent brief comment, applies label.
`unlabeled`	`ready-for-human`	Maintainer (via skill)	Issue requires human implementation. Skill writes a brief comment summarizing the task, applies label.
`unlabeled`	`wontfix`	Maintainer (via skill)	Issue is spam, duplicate, or out of scope. Skill closes with comment (and writes `.out-of-scope/` for enhancements).
`needs-triage`	`needs-info`	Maintainer (via skill)	Issue is underspecified. Skill posts triage notes capturing progress so far + questions for reporter.
`needs-triage`	`ready-for-agent`	Maintainer (via skill)	Grilling session complete, agent-suitable. Skill writes agent brief comment, applies label.
`needs-triage`	`ready-for-human`	Maintainer (via skill)	Grilling session complete, needs human. Skill writes a brief comment summarizing the task, applies label.
`needs-triage`	`wontfix`	Maintainer (via skill)	Maintainer decides not to action. Skill closes with comment (and writes `.out-of-scope/` for enhancements).
`needs-info`	`needs-triage`	Skill (detects reply)	Reporter has replied. Skill surfaces to maintainer for re-evaluation.

An issue can only move along these transitions. The maintainer can override any state directly (see Quick State Override below), but the skill should flag if the transition is unusual.

当前状态	可流转到的状态	触发方	流转说明
`unlabeled`	`needs-triage`	Skill（首次识别时）	该issue需要维护者评估，Skill给出处理建议后自动添加对应标签。
`unlabeled`	`ready-for-agent`	维护者（通过Skill）	该issue需求已明确，适合Agent处理。Skill编写Agent任务说明评论，添加对应标签。
`unlabeled`	`ready-for-human`	维护者（通过Skill）	该issue需要人工实现。Skill编写简短的任务总结评论，添加对应标签。
`unlabeled`	`wontfix`	维护者（通过Skill）	该issue是垃圾内容、重复内容或超出项目范围。Skill发布关闭说明评论（如果是功能需求还会写入 `.out-of-scope/` 目录），关闭issue。
`needs-triage`	`needs-info`	维护者（通过Skill）	该issue需求描述不明确。Skill发布分类处理笔记，记录当前处理进度以及需要向提交者询问的问题。
`needs-triage`	`ready-for-agent`	维护者（通过Skill）	问询会话完成，需求适合Agent处理。Skill编写Agent任务说明评论，添加对应标签。
`needs-triage`	`ready-for-human`	维护者（通过Skill）	问询会话完成，需要人工处理。Skill编写简短的任务总结评论，添加对应标签。
`needs-triage`	`wontfix`	维护者（通过Skill）	维护者决定不处理该issue。Skill发布关闭说明评论（如果是功能需求还会写入 `.out-of-scope/` 目录），关闭issue。
`needs-info`	`needs-triage`	Skill（检测到回复时）	提交者已回复问题。Skill提醒维护者重新评估该issue。

issue只能按照上述路径流转状态。维护者可以直接覆盖任何状态（参见下文的快速状态覆盖），但如果流转路径不符合常规，Skill需要标记提示。

Invocation

调用方式

The maintainer invokes

/github-triage

then describes what they want in natural language. The skill interprets the request and takes the appropriate action.

Example requests:

"Show me anything that needs my attention"
"Let's look at #42"
"Move #42 to ready-for-agent"
"What's ready for agents to pick up?"
"Are there any unlabeled issues?"

维护者输入

/github-triage

命令，然后用自然语言描述需求，Skill会解读请求并执行对应操作。

请求示例：

"给我展示所有需要我处理的内容"
"我们来看下#42号issue"
"把#42号issue移动到ready-for-agent状态"
"有哪些任务已经准备好可以分配给Agent处理？"
"有没有未打标签的issues？"

Workflow: Show What Needs Attention

工作流：展示待处理内容

When the maintainer asks for an overview, query GitHub and present a summary grouped into three buckets:

Unlabeled issues — new, no labels at all. These have never been triaged.
needs-triage
issues — maintainer needs to evaluate or continue evaluating.
needs-info
issues with new activity — the reporter has commented since the last triage notes comment. Check comment timestamps to determine this.

Display counts per group. Within each group, show issues oldest first (longest-waiting gets attention first). For each issue, show: number, title, age, and a one-line summary of the issue body.

Let the maintainer pick which issue to dive into.

当维护者需要查看概览时，查询GitHub并将内容分为三类展示：

未打标签的issues — 全新的issue，没有任何标签，从未被分类处理过。
标记为
needs-triage
的issues — 需要维护者评估或继续评估的issue。
有新动态的
needs-info
issues — 提交者在上次分类处理笔记发布后新增了评论，可通过评论时间戳判断。

展示每个分类的数量，每个分类内的issue按创建时间从早到晚排序（等待时间最长的优先处理）。每个issue展示：编号、标题、存在时长、issue正文的单行摘要。

让维护者选择要深入处理的issue。

Workflow: Triage a Specific Issue

工作流：分类处理特定issue

Step 1: Gather context

步骤1：收集上下文

Before presenting anything to the maintainer:

Read the full issue: body, all comments, all labels, who reported it, when
If there are prior triage notes comments (from previous sessions), parse them to understand what has already been established
Explore the codebase to build context — understand the domain, relevant interfaces, and existing behavior related to the issue
Read
```
.out-of-scope/*.md
```
files and check if this issue matches or is similar to a previously rejected concept

在向维护者展示任何内容之前：

通读完整issue：正文、所有评论、所有标签、提交者信息、提交时间
如果有之前会话留下的分类处理笔记评论，解析内容了解已确认的信息
浏览代码库构建上下文：理解业务领域、相关接口、和该issue相关的现有功能行为
读取
```
.out-of-scope/*.md
```
文件，检查该issue是否和之前被拒绝的需求匹配或相似

Step 2: Present a recommendation

步骤2：给出处理建议

Tell the maintainer:

Category recommendation: bug or enhancement, with reasoning
State recommendation: where this issue should go, with reasoning
If it matches a prior out-of-scope rejection, surface that: "This is similar to
```
.out-of-scope/concept-name.md
```
— we rejected this before because X. Do you still feel the same way?"
A brief summary of what you found in the codebase that's relevant

Then wait for the maintainer's direction. They may:

Agree and ask you to apply labels → do it
Want to flesh it out → start a grilling session
Override with a different state → apply their choice
Want to discuss → have a conversation

告知维护者以下信息：

分类建议： bug还是功能需求，附带理由
状态建议： 该issue应该流转到哪个状态，附带理由
如果匹配到之前超出范围被拒绝的需求，提示："该需求和
```
.out-of-scope/concept-name.md
```
相似，我们之前拒绝该需求是因为X，您现在是否仍然持相同观点？"
你在代码库中找到的相关信息的简要总结

然后等待维护者的指令，他们可能会：

同意建议并要求你添加标签 → 执行操作
想要完善需求 → 启动问询会话
指定其他状态覆盖你的建议 → 应用他们选择的状态
想要讨论 → 和维护者沟通

Step 3: Bug reproduction (bugs only)

步骤3：Bug复现（仅bug类型）

If the issue is categorized as a bug, attempt to reproduce it before starting a grilling session. This will vary by codebase, but do your best:

Read the reporter's reproduction steps (if provided)
Explore the codebase to understand the relevant code paths
Try to reproduce the bug: run tests, execute commands, or trace the logic to confirm the reported behavior
If reproduction succeeds, report what you found to the maintainer — include the specific behavior you observed and where in the code it originates
If reproduction fails, report that too — the bug may be environment-specific, already fixed, or the report may be inaccurate
If the report lacks enough detail to attempt reproduction, note that — this is a strong signal the issue should move to
```
needs-info
```

The reproduction attempt informs the grilling session and the agent brief. A confirmed reproduction with a known code path makes for a much stronger brief.

如果issue被归类为bug，在启动问询会话之前尝试复现问题。复现方式根据代码库不同而不同，尽最大努力完成：

阅读提交者提供的复现步骤（如果有）
浏览代码库理解相关代码路径
尝试复现bug：运行测试、执行命令、跟踪逻辑确认报告的行为是否存在
如果复现成功，向维护者报告你的发现：包含你观察到的具体行为以及代码中对应的问题来源
如果复现失败，也报告结果：bug可能和环境相关、已经被修复、或者报告内容不准确
如果报告缺少足够的复现信息，标注出来：这是该issue应该流转到
```
needs-info
```
状态的强烈信号

复现尝试的结果会为问询会话和Agent任务说明提供参考，已确认复现且定位到代码路径的bug会生成更完善的任务说明。

Step 4: Grilling session (if needed)

步骤4：问询会话（必要时）

If the issue needs to be fleshed out before it's ready for an agent, interview the maintainer to build a complete specification. Follow the /grill-me pattern:

Ask questions one at a time
Provide a recommended answer for each question
If a question can be answered by exploring the codebase, explore the codebase instead
If there are prior triage notes on this issue, resume from where you left off — never re-ask questions that were already resolved
For bugs: use the reproduction findings to ask targeted questions ("I confirmed this happens because X — should the fix be Y or Z?")

The goal is to reach a point where you can write a complete agent brief. Keep going until you have:

A clear summary of the desired behavior
Concrete acceptance criteria
Key interfaces that may need to change
A clear boundary of what's out of scope

如果issue在分配给Agent之前需要完善需求，向维护者提问来构建完整的需求规范，遵循/grill-me模式：

一次只问一个问题
每个问题给出建议答案
如果某个问题可以通过浏览代码库得到答案，直接查询代码库无需提问
如果该issue有之前的分类处理笔记，从上次中断的地方继续，不要重复询问已经确认的问题
针对bug：使用复现结果提出针对性问题（"我确认该问题是X导致的，修复方案应该选Y还是Z？"）

目标是获取足够信息来编写完整的Agent任务说明，直到你得到以下信息再停止：

期望行为的清晰总结
具体的验收标准
可能需要修改的关键接口
明确的超出处理范围的边界

Step 5: Apply the outcome

步骤5：应用处理结果

Before posting any comment or applying any label, show the maintainer a preview of exactly what will be posted and which labels will be applied/removed. Only proceed on confirmation.

Depending on the outcome:

ready-for-agent — post an agent brief comment (see AGENT-BRIEF.md)
ready-for-human — post a comment summarizing the task, what was established during triage, and why it needs human implementation. Use the same structure as an agent brief but note the reason it can't be delegated to an agent (e.g. requires judgment calls, external system access, design decisions, or manual testing).
needs-info — post triage notes with progress so far and questions for the reporter (see Needs Info Output below)
wontfix (bug) — post a polite comment explaining why, then close the issue
wontfix (enhancement) — write to
```
.out-of-scope/
```
, post a comment linking to it, then close the issue (see OUT-OF-SCOPE.md)
needs-triage — apply the label. Optionally leave a comment if there's partial progress to capture.

在发布任何评论或添加任何标签之前，向维护者展示预览内容：包含即将发布的评论内容、即将添加/移除的标签，只有得到确认后再执行操作。

根据处理结果执行不同操作：

ready-for-agent — 发布Agent任务说明评论（参见AGENT-BRIEF.md）
ready-for-human — 发布评论总结任务、分类处理期间确认的信息、以及需要人工实现的原因。使用和Agent任务说明相同的结构，但注明不能分配给Agent的原因（例如需要判断决策、外部系统访问权限、设计决策、手动测试等）
needs-info — 发布分类处理笔记，记录当前进度以及需要向提交者询问的问题（参见下文的需求信息缺失输出模板）
wontfix（bug类型） — 发布礼貌的解释评论，然后关闭issue
wontfix（功能需求类型） — 写入
```
.out-of-scope/
```
目录，发布评论关联对应文件，然后关闭issue（参见OUT-OF-SCOPE.md）
needs-triage — 应用对应标签，如果有部分进度需要记录可以选择添加评论

Workflow: Quick State Override

工作流：快速状态覆盖

When the maintainer explicitly tells you to move an issue to a specific state (e.g. "move #42 to ready-for-agent"), trust their judgment and apply the label directly.

Still show a confirmation of what you're about to do: which labels will be added/removed, and whether you'll post a comment or close the issue. But skip the grilling session entirely.

If moving to

ready-for-agent

without a grilling session, ask the maintainer if they want to write a brief agent brief comment or skip it.

当维护者明确要求你将某个issue移动到指定状态时（例如"move #42 to ready-for-agent"），信任维护者的判断直接应用对应标签。

仍然需要向维护者展示操作确认信息：即将添加/移除的标签、是否会发布评论或关闭issue，但完全跳过问询会话。

如果未经过问询会话直接移动到

ready-for-agent

状态，询问维护者是否需要编写简短的Agent任务说明评论或者跳过。

Needs Info Output

需求信息缺失输出模板

When moving an issue to

needs-info

, post a comment that captures the grilling progress and tells the reporter what's needed:

markdown

undefined

当将issue移动到

needs-info

状态时，发布如下评论，记录问询进度并告知提交者需要提供的信息：

markdown

undefined

Triage Notes

What we've established so far:

point 1
point 2

What we still need from you (@reporter):

question 1
question 2


Include everything resolved during the grilling session in "established so far" — this work should not be lost. The questions for the reporter should be specific and actionable, not vague ("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 Previous Sessions

恢复之前的会话

When triaging an issue that already has triage notes from a previous session:

Read all comments to find prior triage notes
Parse what was already established
Check if the reporter has answered any outstanding questions
Present the maintainer with an updated picture: "Here's where we left off, and here's what the reporter has said since"
Continue the grilling from where it stopped — do not re-ask resolved questions

当分类处理的issue已经有之前会话留下的分类处理笔记时：

阅读所有评论找到之前的分类处理笔记
解析已确认的信息
检查提交者是否已经回复了未解决的问题
向维护者展示最新的状态："这是我们上次中断的进度，这是提交者之后回复的内容"
从上次中断的地方继续问询，不要重复询问已经解决的问题