triage

Files (4)

• AGENT-BRIEF.md
• OUT-OF-SCOPE.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Triage

按一小套分诊角色状态机，推进项目 issue tracker 上的 issues。

若本仓库把外部 pull requests 当作请求入口（见 issue-tracker 配置），分诊也覆盖它们：**PR 就是带附件代码的 issue**——相同角色、相同状态、同一台机器，下面标了 "for a PR" 的几处有差异。光秃的 `#42` 按 tracker 配置解析为 issue 或 PR。

分诊期间发到 issue tracker 的每条 comment 或 issue **必须**以这段免责声明开头：

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

## 参考文档

- [AGENT-BRIEF.md](AGENT-BRIEF.md) — 如何写耐久的 agent briefs
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — `.out-of-scope/` 知识库如何工作

## 角色

两个**类别**角色：

- `bug` — 有东西坏了
- `enhancement` — 新功能或改进

五个**状态**角色：

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

对 PR 而言，相同状态对照所附代码来读：`ready-for-agent` 表示已附上 brief，agent 应在 diff 上做下一步；`ready-for-human` 表示已准备好由人来 merge。

每个已分诊的 issue 应恰好带一个类别角色和一个状态角色。若状态角色冲突，先标出来问维护者，再做别的事。

这些是规范角色名——issue tracker 实际使用的标签字符串可能不同。映射本应已提供给你——若没有，运行 `/setup-matt-pocock-skills`。

状态转换：未打标签的 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" (issue 或 PR)
- "Move #42 to ready-for-agent"
- "What's ready for agents to pick up?"

## 展示需要关注的事项

查询 issue tracker，按最旧优先呈现三个桶：

1. **Unlabeled** — 从未分诊。
2. **`needs-triage`** — 评估进行中。
3. **`needs-info` 且自上次分诊笔记以来报告者有活动** — 需要重新评估。

当 PRs 在范围内时，把外部 PRs 也放进这些桶，每行标上 `[PR]` 或 `[issue]`。发现面只展示*外部* PRs（tracker 配置定义谁算外部）——协作者进行中的 PR 不是分诊工作。此过滤仅用于发现；明确点名的 PR 无论作者如何都会被分诊。

展示计数，以及每项一行摘要。让维护者挑选。

## 分诊特定 issue 或 PR

1. **收集上下文。** 阅读完整 issue 或 PR（正文、comments、labels、作者、日期；对 PR 还要看 diff）。解析任何先前的分诊笔记，以免重问已解决的问题。用项目领域词汇表探索代码库，尊重该区域的 ADRs。对代码库做两项检查：(a) **冗余** —— 按领域概念（不只是请求的措辞）搜索所请求行为的已有实现，并报告你查了哪里。若找到，这是已实现的 `wontfix`（步骤 5）。(b) **先前拒绝** —— 阅读 `.out-of-scope/*.md`，把任何与本请求相似的提出来。

2. **给出建议。** 告诉维护者你的类别和状态建议及理由，外加与请求相关的简短代码库摘要——包括是否已经实现。等待指示。

3. **核实主张。** 在任何 grilling 之前，检查主张是否站得住。对 bug，按报告者的步骤复现。对 PR，确认 diff 做了它声称的事——checkout，跑相关 tests 或命令。报告发生了什么：已确认（带代码路径）、失败，或细节不足（强烈的 `needs-info` 信号）。已确认的核实会让 agent brief 有力得多。

4. **Grill（若需要）。** 若请求需要充实，一起运行 `/grilling` 和 `/domain-modeling` skills——一轮问题一轮地 grill 成形，打磨领域术语，决策落地时就地更新 `CONTEXT.md`/ADRs。

5. **应用结果：**
   - `ready-for-agent` — 发一条 agent brief comment（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
   - `ready-for-human` — 结构与 agent brief 相同，但注明为何不能委派（判断调用、外部访问、设计决策、手工测试）。
   - `needs-info` — 发分诊笔记（模板见下）。
   - `wontfix` — 关闭，comment 取决于*原因*：
     - **已经实现** — 该变更已存在于代码库。指出它所在位置；**不要**写入 `.out-of-scope/`（该知识库用于*被拒绝*的请求，不是已做成的）。
     - **拒绝（bug）** — 礼貌说明，然后关闭。
     - **拒绝（enhancement）** — 写入 `.out-of-scope/`，在 comment 里链过去，然后关闭（[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
   - `needs-triage` — 应用该角色。若有部分进展，comment 可选。

## 快速状态覆盖

若维护者说 "move #42 to ready-for-agent"，信任他们并直接应用该角色。确认你即将做的事（角色变更、comment、关闭），然后行动。跳过 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" 下，以免工作丢失。问题必须具体可执行，而不是 "please provide more info"。

## 恢复先前会话

若 issue 或 PR 上已有先前的分诊笔记，先读它们，检查报告者是否已回答任何未决问题，再呈现更新后的图景然后继续。不要重问已解决的问题。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn