# Triage

> 讓 issues 與外部 PR 穿過分診角色的狀態機——分類、驗證、視需要 grill，並撰寫可供代理使用的簡報。

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

---


# 分診

在專案 Issue 追蹤器上，讓 issues 穿過由分診角色構成的小型狀態機。

如果這個 repo 把外部 pull requests 視為請求介面（見 issue-tracker 設定），分診也涵蓋它們：**PR 就是附帶程式碼的 issue**——相同的角色、相同的狀態、相同的機器，只有下面標註「for a PR」的幾處差異。依追蹤器設定，把孤伶伶的 `#42` 解析成 issue 或 PR。

分診期間貼到 Issue 追蹤器上的每一則評論或 issue，都**必須**以此免責聲明開頭：

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

## 參考文件

- [AGENT-BRIEF.md](AGENT-BRIEF.md) — 如何撰寫耐用的代理簡報
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — `.out-of-scope/` 知識庫如何運作

## 角色

兩個**類別**角色：

- `bug` — 有東西壞了
- `enhancement` — 新功能或改善

五個**狀態**角色：

- `needs-triage` — 需要維護者評估
- `needs-info` — 等待報告人提供更多資訊
- `ready-for-agent` — 規格完整，可供 AFK 代理使用
- `ready-for-human` — 需要人類實作
- `wontfix` — 不會處理

對 PR 而言，相同的狀態要對照附帶的程式碼來解讀：`ready-for-agent` 表示已附上簡報，代理應該在 diff 上採取下一步；`ready-for-human` 表示已準備好由人類合併。

每個已分診的 issue 都應該正好帶一個類別角色和一個狀態角色。如果狀態角色互相衝突，先標註出來並詢問維護者，再做任何其他事。

這些是正式的角色名稱——Issue 追蹤器實際使用的標籤字串可能不同。這個對應關係應該已經提供給你——如果沒有，執行 `/setup-matt-pocock-skills`。

狀態轉移：未加標籤的 issue 通常先進入 `needs-triage`；從那裡移到 `needs-info`、`ready-for-agent`、`ready-for-human` 或 `wontfix`。一旦報告人回覆，`needs-info` 就會回到 `needs-triage`。維護者隨時可以推翻——把看起來不尋常的轉移標註出來，並在繼續前詢問。

## 叫用

維護者叫用 `/triage` 並以自然語言描述他們想要什麼。解讀請求並採取行動。例如：

- 「讓我看任何需要我注意的內容」
- 「我們來看一下 #42」（issue 或 PR）
- 「把 #42 移到 ready-for-agent」
- 「有哪些是代理可以接手的？」

## 顯示需要關注的內容

查詢 Issue 追蹤器，呈現三個類別，最舊的優先：

1. **未加標籤** — 從未分診。
2. **`needs-triage`** — 評估進行中。
3. **自上次分診筆記以來有報告人活動的 `needs-info`** — 需要重新評估。

當 PR 在範圍內時，把外部 PR 納入這些類別，並為每一行標上 `[PR]` 或 `[issue]`。探索只會浮現*外部* PR（追蹤器設定會定義誰算是外部）——協作者進行中的 PR 不是分診工作。這個過濾只影響探索；被明確點名的 PR，無論作者是誰都會被分診。

顯示每個項目的數量與一行摘要。讓維護者挑選。

## 分診特定的 issue 或 PR

1. **收集上下文。** 讀取完整的 issue 或 PR（內文、評論、標籤、作者、日期；若是 PR，還包括 diff）。解析任何先前的分診筆記，這樣你就不會重問已經解決的問題。使用專案的領域詞彙表探索程式碼庫，並尊重該區域的 ADR。對程式碼庫執行兩項檢查：(a) **冗餘**——依領域概念（不只是請求的措辭）搜尋是否已有既有實作，並回報你查過哪裡。如果找到，它就是一項已實作的 `wontfix`（步驟 5）。(b) **先前拒絕**——讀取 `.out-of-scope/*.md`，浮現任何與此請求相似的內容。

2. **建議。** 告訴維護者你的類別與狀態建議及理由，外加與此請求相關的簡短程式碼庫摘要——包括它是否已實作。等待指示。

3. **驗證主張。** 在任何 grilling 之前，先檢查主張是否成立。對 bug，依報告人的步驟重現它。對 PR，確認 diff 做到它所宣稱的事——把它 checkout 出來，執行相關的測試或指令。回報發生的事：已確認（附程式碼路徑）、失敗，或細節不足（一個強烈的 `needs-info` 訊號）。已確認的驗證會讓代理簡報強上許多。

4. **Grill（如果需要）。** 如果請求需要充實內容，就一起運行 `/grilling` 與 `/domain-modeling` 技能——一輪一輪地問問題，把它 grill 成型，磨利領域術語，並在決策落定時就地更新 `CONTEXT.md`/ADR。

5. **套用結果：**
   - `ready-for-agent` — 貼上代理簡報評論（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
   - `ready-for-human` — 結構與代理簡報相同，但要註明為什麼無法委派（需要判斷、外部存取、設計決策、手動測試）。
   - `needs-info` — 貼上分診筆記（見下方範本）。
   - `wontfix` — 關閉，評論依*原因*而定：
     - **已實作** — 這項變更已存在於程式碼庫。指出它在哪裡；**不要**寫入 `.out-of-scope/`（那個知識庫是給*被拒絕*的請求，不是給已建置的）。
     - **拒絕（bug）** — 有禮貌地說明，然後關閉。
     - **拒絕（enhancement）** — 寫入 `.out-of-scope/`，在評論中連結它，然後關閉（[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
   - `needs-triage` — 套用角色。如果已有部分進展，可選擇加上評論。

## 快速狀態覆寫

如果維護者說「把 #42 移到 ready-for-agent」，相信他們並直接套用角色。先確認你即將做的事（角色變更、評論、關閉），然後行動。跳過 grilling。如果在沒有 grilling session 的情況下移到 `ready-for-agent`，詢問他們是否要撰寫代理簡報。

## 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 期間解決的一切記在「已確立內容」之下，這樣工作才不會遺失。問題必須具體且可執行，而不是「請提供更多資訊」。

## 恢復先前的 session

如果 issue 或 PR 上已有先前的分診筆記，讀取它們，檢查報告人是否已回答任何未決問題，並在繼續前呈現更新後的全貌。不要重問已解決的問題。