# Triage

> 通过分诊角色驱动的状态机对 issue 进行分诊。当用户想创建 issue、分诊 issue、审查传入的 bug 或功能请求、为 AFK agent 准备 issue、或管理工作流时使用。 (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: `ninehills/triage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ninehills/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ninehills/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ninehills (https://skillmd.com/u/ninehills)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ninehills/triage

---


# 分诊 (Triage)

通过由分诊角色组成的小型状态机，在项目的 issue 跟踪器中移动 issue。

> Move issues on the project issue tracker through a small state machine of triage roles.

在分诊期间发布到 issue 跟踪器的每条评论或 issue **必须**以以下免责声明开头：

> Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:

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

## 参考文档 (Reference docs)

- [AGENT-BRIEF.md](AGENT-BRIEF.md) — 如何编写持久化的 agent brief
  > How to write durable agent briefs
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — `.out-of-scope/` 知识库如何工作
  > How the `.out-of-scope/` knowledge base works

## 角色 (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` — 完全指定，准备就绪可由 AFK agent 认领
  > Fully specified, ready for an AFK agent
- `ready-for-human` — 需要人工实现
  > Needs human implementation
- `wontfix` — 不会被处理
  > Will not be actioned

每个已分诊的 issue 应恰好携带一个类别角色和一个状态角色。如果状态角色冲突，标记它并在执行其他操作前询问维护者。

> 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.

这些是规范角色名称——issue 跟踪器中使用的实际标签字符串可能不同。映射应该已提供给你——如果没有，请运行 `/setup-matt-pocock-skills`。

> 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.

状态转换：未标记的 issue 通常先进入 `needs-triage`；从那里移动到 `needs-info`、`ready-for-agent`、`ready-for-human` 或 `wontfix`。`needs-info` 在报告者回复后返回 `needs-triage`。维护者可以随时覆盖——标记看起来不寻常的转换，并在继续前询问。

> 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.

## 调用 (Invocation)

维护者调用 `/triage` 并用自然语言描述他们想要什么。解释请求并执行。示例：

> 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"
- "Move #42 to ready-for-agent"
- "What's ready for agents to pick up?"

## 显示需要关注的内容 (Show what needs attention)

查询 issue 跟踪器并呈现三个桶，最旧的优先：

> Query the issue tracker and present three buckets, oldest first:

1. **未标记 (Unlabeled)** — 从未分诊。
   > Never triaged.
2. **`needs-triage`** — 评估进行中。
   > Evaluation in progress.
3. **`needs-info` 且自上次分诊记录以来报告者有活动** — 需要重新评估。
   > **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.

显示计数和每个 issue 的单行摘要。让维护者选择。

> Show counts and a one-line summary per issue. Let the maintainer pick.

## 分诊特定 issue (Triage a specific issue)

1. **收集上下文 (Gather context)。** 读取完整 issue（正文、评论、标签、报告者、日期）。解析任何先前的分诊记录，以避免重复询问已解决的问题。使用项目的领域词汇表探索代码库，尊重相关区域的 ADR。读取 `.out-of-scope/*.md` 并呈现任何与该 issue 相似的先前拒绝记录。
   > Read the full issue (body, comments, labels, reporter, dates). 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. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.

2. **推荐 (Recommend)。** 告诉维护者你的类别和状态推荐及推理，加上与 issue 相关的代码库简要摘要。等待指示。
   > Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.

3. **复现（仅限 bug）(Reproduce (bugs only))。** 在任何深入分析之前，尝试复现：读取报告者的步骤，追踪相关代码，运行测试或命令。报告结果——成功复现并找到代码路径、复现失败、或细节不足（强烈的 `needs-info` 信号）。确认的复现会使 agent brief 更加强大。
   > Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. Report what happened — successful repro with code path, failed repro, or insufficient detail (a strong `needs-info` signal). A confirmed repro makes a much stronger agent brief.

4. **深入分析（如需要）(Grill (if needed))。** 如果 issue 需要充实，运行 `/grill-with-docs` 会话。
   > If the issue needs fleshing out, run a `/grill-with-docs` session.

5. **应用结果 (Apply the outcome)：**
   > Apply the outcome:
   - `ready-for-agent` — 发布 agent brief 评论（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
     > Post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
   - `ready-for-human` — 与 agent brief 结构相同，但注明为什么不能委托（判断性决策、外部访问、设计决策、手动测试）。
     > 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`（bug）— 礼貌解释，然后关闭。
     > Polite explanation, then close.
   - `wontfix`（enhancement）— 写入 `.out-of-scope/`，从评论中链接到它，然后关闭（[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
     > Write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
   - `needs-triage` — 应用角色。如果有部分进展，可选添加评论。
     > Apply the role. Optional comment if there's partial progress.

## 快速状态覆盖 (Quick state override)

如果维护者说"把 #42 移到 ready-for-agent"，信任他们并直接应用角色。确认你将要做什么（角色更改、评论、关闭），然后执行。跳过深入分析。如果在没有深入分析会话的情况下移到 `ready-for-agent`，询问他们是否要编写 agent brief。

> 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.

## Needs-info 模板 (Needs-info template)

```markdown
## 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".

## 恢复之前的会话 (Resuming a previous session)

如果 issue 上存在先前的分诊记录，读取它们，检查报告者是否回答了任何未解决的问题，并在继续之前呈现更新的情况。不要重复询问已解决的问题。

> If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.