GitHub Issue Triage

在当前 repo 中使用 label-based state machine 分诊 issues。通过 git remote 推断 repo。所有 GitHub 操作都使用 gh。

AI Disclaimer

triage 期间发布到 GitHub 的每个 comment 或 issue，comment body 顶部都必须包含以下 disclaimer，且放在任何其他内容之前：

> *This was generated by AI during triage.*

Reference docs

AGENT-BRIEF.md — 如何编写 durable agent briefs
OUT-OF-SCOPE.md — .out-of-scope/ knowledge base 的工作方式

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

每个 issue 应该恰好有一个 state label 和一个 category label。如果 issue 有冲突的 state labels（例如同时有 needs-triage 和 ready-for-agent），先标出冲突并询问 maintainer 哪个 state 正确，再做任何其他事。给出 recommendation。

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.

issue 只能沿这些 transitions 移动。maintainer 可以直接 override 任意 state（见 Quick State Override），但 skill 应标出异常 transition。

Invocation

maintainer 调用 /github-triage，然后用自然语言描述想做什么。skill 解释请求并采取相应 action。

示例请求：

"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?"

Workflow: Show What Needs Attention

当 maintainer 要 overview 时，查询 GitHub，并按三组展示 summary：

Unlabeled issues — 新 issue，没有任何 labels，从未 triaged。
needs-triage issues — maintainer 需要评估或继续评估。
needs-info issues with new activity — reporter 在最后一条 triage notes comment 之后又评论了。检查 comment timestamps 来判断。

显示每组数量。组内按 oldest first 展示（等待最久的优先）。每个 issue 显示 number、title、age，以及 issue body 的一行 summary。

让 maintainer 选择要深入哪个 issue。

Workflow: Triage a Specific Issue

Step 1: Gather context

在向 maintainer 展示任何内容之前：

读取完整 issue：body、所有 comments、所有 labels、reporter、时间
如果有先前 triage notes comments，解析它们以理解已经确认的内容
探索 codebase 来建立 context：理解与 issue 相关的 domain、interfaces 和 existing behavior
读取 .out-of-scope/*.md files，检查该 issue 是否匹配或类似先前 rejected concept

Step 2: Present a recommendation

告诉 maintainer：

Category recommendation: bug 或 enhancement，并说明理由
State recommendation: issue 应该流向哪里，并说明理由
如果它匹配先前 out-of-scope rejection，展示：“This is similar to .out-of-scope/concept-name.md — we rejected this before because X. Do you still feel the same way?”
简要总结你在 codebase 中发现的相关内容

然后等待 maintainer 指示。他们可能：

同意并要求应用 labels → 执行
想把它补充完整 → 开始 /domain-model session
用不同 state override → 应用他们的选择
想讨论 → 继续对话

Step 3: Bug reproduction (bugs only)

如果 issue 被归类为 bug，在开始 /domain-model session 前尝试复现。不同 codebase 会不同，但尽力：

读取 reporter 的 reproduction steps（如果有）
探索 codebase，理解相关 code paths
尝试复现 bug：运行 tests、执行 commands，或追踪 logic 来确认 reported behavior
如果复现成功，向 maintainer 报告发现：包括观察到的具体 behavior，以及它源自代码中的哪个概念区域
如果复现失败，也要报告；bug 可能依赖环境、已经修复，或报告不准确
如果报告缺少足够细节而无法复现，记录这一点；这是 issue 应移到 needs-info 的强信号

复现尝试会影响 /domain-model session 和 agent brief。确认复现并知道 code path，会让 brief 强很多。

Step 4: /domain-model session (if needed)

如果 issue 还需要补充细节才能交给 agent，就访谈 maintainer，建立完整 specification。使用 /domain-model skill。

Step 5: Apply the outcome

根据结果：

ready-for-agent — 发布 agent brief comment（见 AGENT-BRIEF.md）
ready-for-human — 发布 comment，总结 task、triage 中已确认内容，以及为什么需要人类实现。结构与 agent brief 相同，但注明不能 delegate 给 agent 的原因（例如需要 judgment calls、external system access、design decisions 或 manual testing）。
needs-info — 发布 triage notes，包含目前进展和给 reporter 的问题（见 Needs Info Output）
wontfix (bug) — 发布礼貌 comment 解释原因，然后 close issue
wontfix (enhancement) — 写入 .out-of-scope/，发布链接到它的 comment，然后 close issue（见 OUT-OF-SCOPE.md）
needs-triage — 应用 label。如果有部分进展要保存，可以选择留 comment。

Workflow: Quick State Override

当 maintainer 明确要求把 issue 移到某个 state（例如 "move #42 to ready-for-agent"），信任其判断并直接应用 label。

仍然展示即将执行的确认：会添加/移除哪些 labels，是否会发布 comment 或 close issue。但完全跳过 /domain-model session。

如果不经过 /domain-model session 就移到 ready-for-agent，询问 maintainer 是要写一个简短 agent brief comment，还是跳过。

Needs Info Output

移动 issue 到 needs-info 时，发布 comment，捕获访谈进展并告诉 reporter 还需要什么：

## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2

把 /domain-model session 中已解决的所有内容放入 "established so far"，不要丢失这部分工作。给 reporter 的问题必须具体、可执行，不要含糊地写“please provide more info”。

Resuming Previous Sessions

分诊已有先前 triage notes 的 issue 时：

读取所有 comments，找到先前 triage notes
解析已经确认的内容
检查 reporter 是否回答了未解决问题
向 maintainer 展示更新后的 picture：“Here's where we left off, and here's what the reporter has said since”
从上次停止处继续 /domain-model session，不要重复询问已解决的问题

github-triage