triage

Matt Pocock ｜ 規劃與釐清 ｜ 原文 ｜ MIT

讓 issue 和外部 PR 走過 triage 狀態機

---
name: triage
description: 讓 issue 和外部 PR 依著 triage 角色的狀態機流轉：分類、驗證、必要時 grilling，並寫出 agent 可以直接接手的 brief。
disable-model-invocation: true
---

# Triage

讓專案 issue tracker 上的 issue，依著一個小型的 triage 角色狀態機流轉。

如果這個 repo 把外部 pull request 當成請求入口（見 issue-tracker 設定），triage 也涵蓋它們：**PR 就是附帶程式碼的 issue**，用同樣的角色、同樣的狀態、同一個狀態機，只有下面標示「for a PR」的幾個差異。單獨一個 `#42` 要依 tracker 設定判斷它是 issue 還是 PR。

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/` 知識庫怎麼運作

## 角色

兩個**類別**角色：

- `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 了。

每個經過 triage 的 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. **沒有標籤**：從來沒 triage 過。
2. **`needs-triage`**：評估進行中。
3. **`needs-info`，而且自上次 triage 筆記之後回報者有新動態**：需要重新評估。

當 PR 在範圍內時，把外部 PR 也放進這些分組，每一行標上 `[PR]` 或 `[issue]`。探索時只會浮現*外部*的 PR（誰算外部由 tracker 設定定義），所以協作者進行中的 PR 不算 triage 的工作。這個過濾只用在探索；明確指名的 PR 不論作者是誰，一律會 triage。

顯示數量和每個項目的一句話摘要。讓維護者自己挑。

## Triage 特定的 issue 或 PR

1. **蒐集 context。** 讀完整的 issue 或 PR（內容、留言、標籤、作者、日期；PR 還要看 diff）。解析之前的 triage 筆記，這樣就不會重複問已經解決的問題。用專案的領域詞彙表探索 codebase，並尊重該區的 ADR。對 codebase 做兩項檢查：(a) **重複**：依領域概念（不只是請求的字面措辭）搜尋所請求行為的既有實作，並回報你找過哪些地方。如果找到了，它就是「已經實作」的 `wontfix`（第 5 步）。(b) **先前被否決過**：讀 `.out-of-scope/*.md`，把任何跟這個請求相似的都拿出來。

2. **給建議。** 告訴維護者你對類別和狀態的建議與理由，再加上跟這個請求相關的 codebase 簡短摘要（包括它是不是已經實作了）。等待指示。

3. **驗證說法。** 在任何 grilling 之前，先檢查這個說法站不站得住腳。對 bug，照回報者的步驟重現它。對 PR，確認 diff 真的做到它所宣稱的：checkout 下來，跑相關的測試或指令。回報發生了什麼：已確認（附上程式碼路徑）、失敗，或細節不足（這是強烈的 `needs-info` 訊號）。確認過的驗證會讓 agent brief 強很多。

4. **Grilling（如果需要）。** 如果請求需要充實，就用 Skill 工具呼叫兩次，分別是 "grilling" 和 "domain-modeling"，一回合一回合地把它 grill 成形，在決策定案的當下，同步磨利領域術語並更新 `GLOSSARY.md`/ADR。

5. **套用結果：**
   - `ready-for-agent`：發一則 agent brief 留言（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
   - `ready-for-human`：結構跟 agent brief 一樣，但要註明為什麼不能委派（需要判斷、需要外部權限、設計決策、手動測試）。
   - `needs-info`：發 triage 筆記（範本如下）。
   - 對 `wontfix`，關閉 issue，留言內容依*原因*而定：
     - **已經實作**：這個改動在 codebase 裡已經存在。指出它在哪裡；**不要**寫進 `.out-of-scope/`（那個知識庫是給*被否決*的請求，不是已經做好的）。
     - **被否決（bug）**：禮貌地說明，然後關閉。
     - **被否決（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」底下，這樣工作成果才不會遺失。問題必須具體、可執行，不能只是「請提供更多資訊」。

## 接續之前的 session

如果 issue 或 PR 上有之前的 triage 筆記，就讀它們，檢查回報者有沒有回答任何未解的問題，並在繼續之前呈現更新後的全貌。不要重複問已經解決的問題。

---
name: triage
description: Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
disable-model-invocation: true
---

# Triage

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

If this repo treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: **a PR is an issue with attached code**, using the same roles, same states, and same machine, with a few deltas marked "for a PR" below. Resolve a bare `#42` to an issue or PR per the tracker config.

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): how to write durable agent briefs
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md): 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`: fully specified, ready for an AFK agent
- `ready-for-human`: needs human implementation
- `wontfix`: will not be actioned

For a PR, the same states read against the attached code: `ready-for-agent` means a brief is attached and an agent should take the next step on the diff; `ready-for-human` means it's ready for a human to merge.

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.

These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.

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

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

## Show what needs attention

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

1. **Unlabeled**: never triaged.
2. **`needs-triage`**: evaluation in progress.
3. **`needs-info` with reporter activity since the last triage notes**: needs re-evaluation.

When PRs are in scope, include external PRs in these buckets and tag each line `[PR]` or `[issue]`. Discovery surfaces only *external* PRs (the tracker config defines who counts as external), so a collaborator's in-flight PR is not triage work. This filter is discovery-only; an explicitly named PR is always triaged regardless of author.

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

## Triage a specific issue or PR

1. **Gather context.** Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). 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. Run two checks against the codebase: (a) **redundancy**: search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection**: read `.out-of-scope/*.md` and surface any that resembles this request.

2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request (including whether it's already implemented). Wait for direction.

3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims: check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.

4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms and updating `GLOSSARY.md`/ADRs inline as decisions land.

5. **Apply the outcome:**
   - `ready-for-agent`: post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
   - `ready-for-human`: 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).
   - For `wontfix`, close the issue, with the comment depending on *why*:
     - **Already implemented**: the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones).
     - **Rejected (bug)**: give a polite explanation, then close.
     - **Rejected (enhancement)**: 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

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

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