Reference · User-invoked · On-ramp（tracker 的定期保养）

triage 速查

Issue tracker 分诊状态机的口袋版。完整教学见 Lesson 0014；原文见 SKILL.md、 AGENT-BRIEF.md、 OUT-OF-SCOPE.md。

一句话

把 tracker 里别人创建的原始 issue / 外部 PR 推过一台状态机：分类 → 验证 → 必要时烤（grilling + domain-modeling）→ 落地标签与评论，最终产出 AFK agent 能接的 brief。只能人启动（disable-model-invocation: true）；每条发出去的评论以 > *This was generated by AI during triage.* 开头。

何时用 / 不用

用：bug 报告与功能请求堆积；「给我看看需要操心的」「看 #42」「把 #42 移到 ready-for-agent」
不用：to-tickets 切出的 issue（出生即 agent-ready）；现在就修的 bug → diagnosing-bugs；对话 → tracker 是 to-spec（方向相反）
前置：setup-matt-pocock-skills 已写好 docs/agents/issue-tracker.md + triage-labels.md

七个 Triage role（词汇表）

Category（恰好一个）: bug 有东西坏了 · enhancement 新功能或改进
State（恰好一个；冲突 → 先问维护者）: needs-triage 待评估 · needs-info 等报告者补充 · ready-for-agent 规格完整、agent 可接 · ready-for-human 需人来实现/合并 · wontfix 不处理（已实现或已拒绝）
流转: 无标签 → needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix；报告者回复后 needs-info → needs-triage；维护者可覆盖，异常流转先问

PR 规则

PR = 带代码的 issue，同一台状态机；状态对着 diff 读（ready-for-human ≈ 可合并）
开关：issue-tracker.md 的「PRs as a request surface」（setup 默认 no）
发现只收外部 PR（GitHub：authorAssociation ∈ CONTRIBUTOR / FIRST_TIME_CONTRIBUTOR / NONE）；点名的 PR 不限作者

总览三桶（最老在前）

无标签（从没分诊过）
needs-triage（评估进行中）
needs-info 且报告者自上次分诊笔记后有新活动（该重估了）

五步流水线

收集：读全 issue/PR（PR 含 diff）+ 历史分诊笔记；按领域概念查冗余；查 .out-of-scope/
建议：给分类 + 状态 + 理由 + 代码库摘要，然后等指示
验证：bug 按步骤重现；PR checkout 跑测试 → confirmed（带代码路径）/ failed / 细节不足（强 needs-info 信号）
烤（按需）：/grilling + /domain-modeling 一起，一次一问，就地更新 CONTEXT.md / ADR
落地：ready-for-agent → 发 agent brief；ready-for-human → 同结构 + 为何不能委派；needs-info → 分诊笔记模板；wontfix → 关闭（三分支见下）；needs-triage → 只贴标签

快速通道：维护者直接下状态命令 → 信任、跳过烤、行动前复述确认；进 ready-for-agent 未烤过 → 问要不要补 brief。恢复：有历史分诊笔记 → 先读、查已答问题、不重问。

wontfix 三分支

为什么关	评论	.out-of-scope/
已实现	指出功能在代码里的位置	不写（会毒化去重）
拒绝（bug）	礼貌解释	不写
拒绝（enhancement，含 PR）	链接到概念文件	写/追加 Prior requests

Agent brief 四原则（AGENT-BRIEF.md）

耐放 > 精确：点类型/签名/配置形状；禁文件路径、行号、假设现有结构
行为非步骤：写该做什么，不写怎么实现
验收标准：具体、可测、逐条独立可验证
范围边界：明说不做什么，防镀金

骨架：Category / Summary / Current / Desired / Key interfaces / Acceptance criteria / Out of scope。PR 版：Current 描述 diff 现状，brief = 把这份 diff 做完修好。brief 是合同，原始讨论只是背景。

.out-of-scope/ 知识库（OUT-OF-SCOPE.md）

一概念一文件，kebab-case 命名；文风像小设计文档；理由要实质且耐放（「太忙」不算）
分诊第一步必读；按概念相似度匹配（night theme ≈ dark-mode）
维护者三回应：Confirm（追加 Prior requests 后关闭）/ Reconsider（删改文件，走正常分诊）/ Disagree（照常）
反悔 → 删文件，不重开历史 issue

副作用矩阵

写到哪里	写什么
tracker 标签	恰好一分类 + 一状态（经 triage-labels.md 映射）
tracker 评论	agent brief / 分诊笔记 / wontfix 说明；全带 AI disclaimer
tracker 状态	wontfix 时关闭 issue
`.out-of-scope/*.md`	仅被拒 enhancement：新建/追加/删改
`CONTEXT.md` / ADR	第四步经 domain-modeling 就地更新
不写	实现代码、测试、spec（那是 implement/tdd/to-spec）

下一步

队列清空 → 从 ready-for-agent 列挑一条 /implement（内部驱动 /tdd），每条间清上下文
请求太大形状不清 → 当想法进 /grill-with-docs 主流程
验证出真 bug 想马上修 → /diagnosing-bugs

微调入口（症状 → 改哪）

标签不存在/重复 → 项目仓库 docs/agents/triage-labels.md 右列（别改 SKILL.md 的规范角色名）
没验证就写「已确认」→ SKILL.md 第三步 Verify the claim
brief 带路径行号会过期 → AGENT-BRIEF.md Durability 一节
bug/已实现也写进 .out-of-scope → SKILL.md 第五步 + OUT-OF-SCOPE.md When to write
合作者 PR 混进队列 / 外部 PR 不出现 → issue-tracker.md 的外部定义 / request-surface 开关
评论缺 disclaimer → SKILL.md 开头 must 条款
重问已答问题 → SKILL.md Resuming 一节
AI 擅自启动 → frontmatter + agents/openai.yaml（应双禁）