AGENT SKILL

triage

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

License 许可
MIT
最近更新
2026-11-01
Stars
★ 4
Forks
0

01 前言 Front Matter

name
triage
description
讓 issues 與外部 PR 穿過分診角色的狀態機——分類、驗證、視需要 grill,並撰寫可供代理使用的簡報。
disable-model-invocation
true

02 资源文件 3

03 SKILL.md 正文

分診

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

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

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

> *This was generated by AI during triage.*

參考文件

角色

兩個類別角色:

  • 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 成型,磨利領域術語,並在決策落定時就地更新 GLOSSARY.md/ADR。

  5. 套用結果:

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

快速狀態覆寫

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

Needs-info 範本

## 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 上已有先前的分診筆記,讀取它們,檢查報告人是否已回答任何未決問題,並在繼續前呈現更新後的全貌。不要重問已解決的問題。

04 同仓库更多 Skills