/triage 技能

它的作用

triage works through the issues on your project's tracker. It moves each one through a small state machine of 分流角色 (a category role and a state role). Each issue ends as an agent-ready brief, a specific question for the reporter, or a closed issue with a recorded reason.

它只用于 你没创建的. That means raw bug reports, incoming feature requests, or an external pull request that arrived unannounced: work that came into the tracker from outside, in whatever shape the reporter left it. 任务 from to-tickets are already agent-ready, so if you run triage over them, you waste the work. The rule is simple: /triage 只用于外部进来的 issue，不用于你自己创建的 issue。

It also differs from labelling by hand because it recommends and then waits. It gives you its category and state call with reasoning, plus what it found in the codebase, and applies nothing until you tell it to.

何时使用

你通过输入 /triage and then describing what you want in plain language. The agent won't reach for it on its own. Examples: "Show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent".

前置条件

triage 读写你的 issue 追踪器，所以 setup-matt-pocock-skills must first configure that tracker and its label vocabulary. The role names below are canonical. The label strings in your tracker may differ, and setup provides the mapping. If your tracker already uses the canonical names exactly, you have nothing to map and nothing to set up.

The tracker config also decides whether external pull requests count as a request surface, and who counts as external. That flag is off by default, and setup no longer asks about it. To bring PRs into scope, turn it on in docs/agents/issue-tracker.md.

状态机

Every triaged item ends with exactly one category role and one state role. There are two categories: bug （有东西坏了）和 enhancement (new feature or improvement). There are five states:

That is the whole vocabulary. The rule of exactly one state role per item keeps the queries simple. The states are also the most-requested area of the skill. Users have asked for a state for work that is specified but blocked on another issue, a deferred state for work that waits on a future trigger, and a terminal implemented 状态。这些都没有发布。见下面的问题。

wontfix has three cases. The difference matters because only one of them writes to the knowledge base:

.out-of-scope/ holds one markdown file per rejected concept, not per issue. Each file is a short design document, not a database row. It says what was rejected, why, and lists every issue that asked for it. triage reads the whole directory before it evaluates anything. It matches by concept, not keyword, so "night theme" matches dark-mode.md. When it finds a match, it shows you the old decision and asks if you still agree with it, instead of arguing the request again from the start.

简报前先验证

在任何 追问审视, triage checks that the claim holds. For a bug, it reproduces it from the reporter's steps. For a PR, it checks out the branch and runs the relevant tests. Then it reports one of three results:

• Confirmed, with the code path.
• Failed to reproduce.
• Not enough detail to try. This is the strongest needs-info 信号了。

In the same pass, it runs two more checks against the codebase. The redundancy check asks if the feature is already implemented, and searches by domain concept, not by the reporter's wording. The 先前的否决 check asks if .out-of-scope/ already says no. Both checks are cheap, and a hit on either produces a wontfix.

All of this work makes one artifact good: the 智能体简报. This is the structured comment that triage posts when an issue moves to ready-for-agent. After triage posts it, the brief is the contract and the original report is only context. Briefs are durable 而不是精确，因为一个 issue 可能停在 ready-for-agent for weeks while the code changes. So a brief names types, signatures and behavioural contracts, and never file paths or line numbers. A confirmed reproduction makes a much stronger brief than a guess.

PR 就是带代码的 issue

If the tracker treats external pull requests as a request surface, they go through the same machine, with the same categories, states and transitions. The states apply to the diff. ready-for-agent means a brief is attached and an agent should take the next step on the code. ready-for-human means a person can merge it. A brief on a PR describes what is left to do to the existing diff, not how to build the thing from nothing.

Discovery shows only external PRs, because a collaborator's in-progress branch is not triage work. That filter applies only to discovery. If you name a PR explicitly, triage handles it, whoever wrote it.

常见问题

我运行了 /to-spec and /to-tickets，而现在那些任务躺在那儿没人分流。我该运行 /triage 处理它们？ No. They are already agent-ready. to-tickets 应用 ready-for-agent label when it publishes them, so an AFK runner picks them up without another pass. The user who hit this had run the spec flow and seen needs-triage on the output, and their AFK runner ignored everything. triage is the on-ramp for work that arrives from outside. The spec flow is the lane for work you start yourself. The two meet at ready-for-agent，而不是之前。

是 triage 在有 to-spec → to-tickets → implement 流程？ 只有你有外部进来的工作才需要。 triage is older than that flow and does a different job: it handles reports other people filed. If everything in your tracker came from your own planning, you will rarely use it. If you maintain anything public, or your team files bugs to you, it is where that work starts. The main use is open-source repos that take issues from external contributors.

智能体试图应用 ready-for-agent and gh 说标签不存在。 This is a known open bug (#616）。 setup-matt-pocock-skills 把标签词汇写入 docs/agents/triage-labels.md，但不会在你的追踪器中创建标签。请自行创建五个状态标签和两个分类标签，只需一次，使用 gh label create or the tracker's UI, and the error stops. The issue links to a community fix branch that has not been merged.

Five states aren't enough. What about blocked, or deferred, or implemented? This is the most-filed gap on the skill. It comes in three forms:

• An issue that is fully specified but waits on another issue to close (#139). The reporter said ready-for-agent is "technically true" there but misleading, so an agent picks it up and gets stuck.
• Future work that is intended but waits on a trigger, so it is not actionable yet (#297）。
• A terminal state for "implemented, awaiting verification". Without it, an AFK runner can queue finished tickets again.

The blocked case is accepted as real, but the name is undecided (blocked versus paused). None of it has shipped. As a workaround, people add a repo-local extra label next to the category. The state slot then holds an accurate value, but the skill does not know about the extra label. One community fork goes further and adds needs-slicing, tracking and effort labels. That works, but it belongs to that fork, not to the skill.

这与 /diagnosing-bugs? The verification step here is shallow on purpose. It answers "is this real, and roughly where does it live", and does not look for a root cause. If a bug does not reproduce from the reporter's steps in a few minutes, use needs-info, or use diagnosing-bugs if you want to investigate it now. Neither skill's text mentions the other yet. A user reported that gap, and it is still open.

我能让它指向我整个待办清单让它跑吗？ You can ask, but watch what it reads. The "show what needs attention" pass is a cheap listing for selection. You pick one issue, and then triage gathers full context on that issue. If you run it across twenty issues at once, the agent can use that cheap listing as its only evidence without telling you. The listing returns issue bodies but not comments. One user hit exactly this. Three issues already had a comment that said "already fixed, recommend closing", and all three got new agent briefs instead. For a bulk pass, say explicitly that it must read the comments on each issue.

它能与 Linear 或 GitHub Issues 之外的任何东西配合吗？ Yes. The tracker is config, not a hard-coded assumption. People run it against Linear (through the linear CLI）、GitLab，以及 .scratch/. A common split is Linear for issues and planning, and GitHub for code and PRs. Skills that say "issue tracker" then map to Linear, and skills that say "PR" map to GitHub. The local-markdown tracker has an open template bug: the generated file can contain the acceptance criteria twice, once at the top level and once inside the agent brief (#200）。

做到以下就算成功

• Every item it touches ends with exactly one category role and one state role, never zero, and never two conflicting states.
• It gives you a recommendation with reasoning and stops. It does not relabel the issue and move on.
• It reproduced the bug, or checked out and ran the PR, before anything reached ready-for-agent.
• 它写的简报点名类型和行为，不包含文件路径和行号。
• When a request you rejected six months ago comes back, it tells you and quotes the old reason instead of triaging it again.
• Every comment it posts starts with > *This was generated by AI during triage.*

在流程中的位置

triage 是一个 on-ramp, not a step in the main chain. The main flow starts from an idea you had (grill, spec, tickets, implement, review). triage is the parallel lane for work that came from someone else. Both lanes end at the same place: an issue labelled ready-for-agent with a brief on it. implement picks that up the same way it picks up a ticket from to-tickets. When a request needs more detail before triage can brief it, triage runs 追问审视 and domain-modeling together, one round of questions at a time, so it records decisions in GLOSSARY.md and the ADRs as you make them. When you're not sure which lane you are in, ask-matt 为你指路。