# Triage

> Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.

- Skill: `swm8023/triage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add swm8023/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swm8023/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: swm8023 (https://skillmd.com/u/swm8023)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swm8023/triage

---


# Triage

通过由 triage 角色驱动的小型状态机，在项目 issue tracker 上推进 issue 的流转。

triage 期间在 issue tracker 上发布的每一条评论或 issue **必须**以下面这条免责声明开头：

```
> *This was generated by AI during triage.*
```

## 参考文档

- [AGENT-BRIEF.md](AGENT-BRIEF.md) —— 如何撰写持久可用的 agent brief
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) —— `.out-of-scope/` 知识库的工作方式

## 角色

两个**类别（category）**角色：

- `bug` —— 某些东西坏了
- `enhancement` —— 新特性或改进

五个**状态（state）**角色：

- `needs-triage` —— 维护者需要评估
- `needs-info` —— 等待报告者提供更多信息
- `ready-for-agent` —— 规格完整，已准备好交给 AFK agent
- `ready-for-human` —— 需要人类实现
- `wontfix` —— 不会处理

每个被 triage 过的 issue 应当恰好携带一个 category 角色和一个 state 角色。如果 state 角色相互冲突，先标记出来并询问维护者，然后再做其他事情。

这些是规范化的角色名 —— 在 issue tracker 中实际使用的 label 字符串可能不同。映射关系应当已经提供给你 —— 如果没有，请运行 `/setup-matt-pocock-skills`。

状态转移：一个未打 label 的 issue 通常先进入 `needs-triage`；之后再转为 `needs-info`、`ready-for-agent`、`ready-for-human` 或 `wontfix`。`needs-info` 在报告者回复后回到 `needs-triage`。维护者可以随时覆盖 —— 如果转移看起来异常，先标记出来，并在继续之前询问。

## 调用方式

维护者调用 `/triage` 并用自然语言描述他们想做什么。理解请求并采取行动。示例：

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

## 展示需要关注的内容

查询 issue tracker，并按从旧到新的顺序展示三个分组：

1. **Unlabeled** —— 从未被 triage 过。
2. **`needs-triage`** —— 评估正在进行中。
3. **`needs-info` 且自上次 triage notes 之后报告者有新动作的** —— 需要重新评估。

展示数量统计，并对每个 issue 给出一行摘要。让维护者来挑选。

## 对具体 issue 进行 triage

1. **收集 context。** 阅读完整的 issue（正文、评论、label、报告者、日期）。解析任何先前的 triage notes，这样你就不会重复询问已解决的问题。结合项目的领域术语表探索代码库，并尊重该领域的 ADR。阅读 `.out-of-scope/*.md`，并指出任何与此 issue 相似的先前拒绝记录。

2. **给出建议。** 把你对 category 和 state 的建议连同推理过程告诉维护者，并附上与该 issue 相关的简要代码库摘要。等待指示。

3. **复现（仅限 bug）。** 在任何 grilling 之前，先尝试复现：阅读报告者的步骤，跟踪相关代码，运行测试或命令。汇报发生了什么 —— 成功复现并指出代码路径、复现失败，或者细节不足（这是一个强烈的 `needs-info` 信号）。一个被确认的复现能造就一份强得多的 agent brief。

4. **Grill（如有需要）。** 如果该 issue 需要进一步充实，运行一次 `/grill-with-docs` 会话。

5. **落实结论：**
   - `ready-for-agent` —— 发布一条 agent brief 评论（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
   - `ready-for-human` —— 与 agent brief 结构相同，但要说明为何不能委派（需要主观判断、外部访问、设计决策、手工测试）。
   - `needs-info` —— 发布 triage notes（模板见下文）。
   - `wontfix`（bug）—— 给出礼貌的解释，然后关闭。
   - `wontfix`（enhancement）—— 写入 `.out-of-scope/`，在评论中链接到它，然后关闭（[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
   - `needs-triage` —— 打上该角色。如果有部分进展，可以选择性地附一条评论。

## 快速状态覆盖

如果维护者说 "move #42 to ready-for-agent"，相信他们并直接应用该角色。先确认你将要做的事情（角色变更、评论、关闭），然后行动。跳过 grilling。如果在没有 grilling 会话的情况下转入 `ready-for-agent`，要询问他们是否希望撰写一份 agent brief。

## Needs-info 模板

```markdown
## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2
```

把 grilling 期间已解决的所有内容都记录到 "established so far" 之下，这样工作成果就不会丢失。问题必须是具体且可行动的，而不是 "请提供更多信息"。

## 恢复先前的会话

如果该 issue 上已存在先前的 triage notes，阅读它们，检查报告者是否回答了任何尚未解决的问题，并在继续之前给出一个更新后的全景。不要重复询问已解决的问题。