# Triage

> Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.

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

---


# Triage

将项目 Issue tracker 上的 Issues 移动过一个小型 Triage roles state machine。

如果这个 repo 将 external pull requests 视为 request surface（见 Issue tracker config），triage 也覆盖它们：**PR 是一个附带 code 的 Issue**：相同 roles、相同 states、相同 machine；只有少数差异会在下文标为 “for a PR”。裸 `#42` 应按 tracker config resolve 为 Issue 或 PR。

Triage 期间发布到 Issue tracker 的每条 comment 或 Issue **必须**以此 disclaimer 开头：

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

## Reference docs

- [AGENT-BRIEF.zh.md](AGENT-BRIEF.md) — 如何写 durable agent briefs
- [OUT-OF-SCOPE.zh.md](OUT-OF-SCOPE.md) — `.out-of-scope/` knowledge base 如何工作

## Roles

两个 **category** roles：

- `bug` — 某些东西坏了
- `enhancement` — 新 feature 或 improvement

五个 **state** roles：

- `needs-triage` — maintainer 需要 evaluate
- `needs-info` — 等待 reporter 提供更多 information
- `ready-for-agent` — fully specified，ready for an AFK agent
- `ready-for-human` — 需要 human implementation
- `wontfix` — 不会 action

对 PR 来说，相同 states 要按 attached code 理解：`ready-for-agent` 表示已附 agent brief，agent 应该对 diff 执行下一步；`ready-for-human` 表示它已经 ready for human to merge。

每个 triaged Issue 应恰好携带一个 category role 和一个 state role。如果 state roles 冲突，flag it，并在做其他事前询问 maintainer。

这些是 canonical role names；Issue tracker 中实际 label strings 可能不同。Mapping 应该已经提供给你；如果没有，运行 `/setup-matt-pocock-skills`。

State transitions：unlabeled Issue 通常先进入 `needs-triage`；然后从那里移动到 `needs-info`、`ready-for-agent`、`ready-for-human` 或 `wontfix`。`needs-info` 在 reporter 回复后回到 `needs-triage`。Maintainer 可随时 override；对看起来 unusual 的 transitions 进行 flag，并在 proceeding 前询问。

## Invocation

Maintainer invoke `/triage` 并用自然语言描述想做什么。Interpret request and act。Examples：

- “Show me anything that needs my attention”
- “Let's look at #42”（Issue 或 PR）
- “Move #42 to ready-for-agent”
- “What's ready for agents to pick up?”

## Show what needs attention

Query Issue tracker，并按 oldest first 展示三个 buckets：

1. **Unlabeled** — 从未 triaged。
2. **`needs-triage`** — evaluation in progress。
3. **`needs-info` with reporter activity since the last triage notes** — 需要 re-evaluation。

当 PRs in scope 时，把 external PRs 纳入这些 buckets，并给每行标注 `[PR]` 或 `[issue]`。Discovery surface 只包含 *external* PRs（tracker config 定义谁算 external）；collaborator's in-flight PR 不是 triage work。这个 filter 只用于 discovery；显式 named PR 总是 triaged，不管 author 是谁。

展示 counts，并给每个 item 一行 summary。让 maintainer 选择。

## Triage a specific issue or PR

1. **Gather context.** 读取完整 Issue 或 PR（body、comments、labels、author、dates；对 PR 也读取 diff）。Parse prior triage notes，避免重新问 resolved questions。使用项目的 domain glossary 探索 codebase，并尊重该区域 ADRs。对 codebase 运行两个 checks：(a) **redundancy** — 按 domain concept（不只是 request wording）搜索 requested behavior 是否已有 implementation，并报告你看过哪里。如果找到了，它就是 already-implemented `wontfix`（step 5）。(b) **prior rejection** — 读取 `.out-of-scope/*.md`，surface 任何类似 request。

2. **Recommend.** 告诉 maintainer 你的 category 和 state recommendation、reasoning，以及与 request 相关的简短 codebase summary，包括它是否 already implemented。等待 direction。

3. **Verify the claim.** 在任何 grilling 前检查 claim 是否成立。对 bug，从 reporter steps reproduce。对 PR，确认 diff 确实做了它声称的事：check it out，运行 relevant tests 或 commands。报告发生了什么：confirmed（with code path）、failed，或 insufficient detail（强 `needs-info` signal）。Confirmed verification 会让 agent brief 强很多。

4. **Grill（if needed）.** 如果 request 需要 fleshing out，同时运行 `/grilling` 和 `/domain-modeling` skills：每轮提出一组问题，把它 grill into shape，打磨 domain terms，并随着 decisions landing inline 更新 `CONTEXT.md`/ADRs。

5. **Apply the outcome:**
   - `ready-for-agent` — 发布 agent brief comment（[AGENT-BRIEF.zh.md](AGENT-BRIEF.md)）。
   - `ready-for-human` — 使用 agent brief 的相同结构，但注明为什么不能 delegate（judgment calls、external access、design decisions、manual testing）。
   - `needs-info` — 发布 triage notes（template below）。
   - `wontfix` — close，comment 取决于 *why*：
     - **Already implemented** — change 已存在于 codebase。指出它在哪里；**不要**写入 `.out-of-scope/`（该 KB 用于 *rejected* requests，不用于已 built 的内容）。
     - **Rejected（bug）** — 礼貌解释，然后 close。
     - **Rejected（enhancement）** — 写入 `.out-of-scope/`，从 comment 链接到它，然后 close（[OUT-OF-SCOPE.zh.md](OUT-OF-SCOPE.md)）。
   - `needs-triage` — 应用该 role。如果有 partial progress，可选发布 comment。

## Quick state override

如果 maintainer 说 “move #42 to ready-for-agent”，信任他们并直接应用 role。确认你将要做什么（role changes、comment、close），然后 act。跳过 grilling。如果在没有 grilling session 的情况下移动到 `ready-for-agent`，询问是否要写 agent brief。

## 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
```

将 grilling 中 resolved 的所有内容捕获到 “established so far”，避免 work lost。Questions 必须 specific 且 actionable，而不是 “please provide more info”。

## Resuming a previous session

如果 Issue 或 PR 上已有 prior triage notes，读取它们，检查 reporter 是否回答了 outstanding questions，并在继续前展示 updated picture。不要重问 resolved questions。