triage

分类处理

在仓库配置的跟踪器上，通过一个小型状态机推进问题。请从 docs/agents/issue-tracker.md 读取跟踪器操作说明，并从 docs/agents/triage-labels.md 读取标签字符串；如果缺少任一文件，请说明情况，并建议先运行 configure-repo 再继续（期间仍可只读地进行分类处理）。

如果跟踪器配置指出外部拉取请求属于请求范围，它们也要经过同一状态机——PR 是附带代码的问题。协作者正在处理中的 PR 不属于分类处理范围；明确点名的 PR 始终在范围内。

你在跟踪器上发布的每条评论都必须以以下原样行开头：

> *This was generated by AI during triage.*

参考资料：agent-brief-template.md — 简报格式及其持久性规则。

状态机

分为两个维度；每个经过分类处理的问题每个维度都恰好带一个标签：

• 类别： bug（行为异常）或 enhancement（新增能力）
• 状态： needs-triage → needs-info / shaping / ready-for-agent / ready-for-human / wontfix 之一

当报告者回复时，needs-info 会返回 needs-triage。这些是规范的角色名称——请应用仓库映射后的标签字符串，绝不要直接使用原始角色名称，除非二者一致。如果某个问题带有相互冲突的状态标签，请标记出来，并在操作前询问用户。

范围规则

仅对用户未通过这组技能自行规划的问题进行分类处理。可通过正文中的标记识别出一开始就已准备好交给 Agent 的问题——其中包含 Requirements covered: 部分（由 plan-tasks 发布），或以 > *This issue was drafted by AI with 开头的标记行（由 publish-issues 发布）。对这些问题运行分类处理会在已有的真实规范之上叠加第二份较弱的规范。请跳过它们并说明原因。

查看队列

当用户询问“哪些事项需要关注”时，查询跟踪器并展示三个分组，按时间从早到晚排列；每组附上数量，每项附上一行摘要：(1) 未加标签，(2) needs-triage，(3) 自上次分类备注后有报告者活动的 needs-info。如果 PR 在范围内，请在行首标注 [issue] / [PR]。让用户选择。

分类处理单个议题

1. 收集上下文。 阅读完整议题——正文、评论、标签、作者、日期；对于 PR，还要查看差异。阅读之前的分类记录，避免重复询问已经回答过的问题。使用 CONTEXT.md 中的术语表探索相关代码。如果存在 docs/architecture/，且议题涉及其中涵盖的核心部分，则必须使用 inspect-invariants 子技能进行一致性检查，不要在此处自行判断。然后进行两项检查：

   • 冗余检查： 在代码库中搜索所请求行为是否已有实现——按领域概念搜索，而不是按报告者使用的措辞搜索。如果已经实现，则结果为以已实现为由关闭（第 5 步）；收集相关证据（实现位置、调用方式）。如果没有匹配项，记下搜索过的概念。
   • 此前的否决记录： 阅读 .out-of-scope/*.md，找出与此请求相似的概念——按想法匹配，而不是按关键词匹配。如果有匹配项，告知用户此前否决的内容和原因，并询问是否维持该决定。如果没有匹配项，也要记下来。

   完成条件： 两项检查都有书面结果——冗余检查需记录现有实现，或列出搜索过的概念；此前的否决记录检查需指出匹配记录，或说明没有匹配项。

2. 核实问题描述。 在提出建议之前，先测试问题描述是否属实。对于错误：按照报告者提供的步骤复现。对于 PR：检出差异并运行相关测试或命令，确认其实现了所述内容。报告以下结果之一：已确认（附代码路径）、无法复现，或信息不足——最后一种情况强烈表明需要 needs-info。完成条件： 必须有亲自取得的证据，而不只是报告者的说法。

3. 提出建议。 告知用户你的类别和状态建议，并说明理由以及步骤 1–2 中取得的证据。如果请求含糊不清或描述不充分，且只有用户才能澄清，则必须使用 clarify-decisions 子技能，逐次提出一个问题，明确后再确定建议。等待用户指示。

4. 执行处理结果：

   • shaping — 已确认的错误，但根本原因尚未查明，因此任务简报需要让 Agent 进行调查。发布 Agent 任务简报，并将原因标记为未确定；同时说明 /shape #N 会运行 root-cause，并编写构建所需的一级简版规格。在对 klynt #242 的四次基线分类处理中，有三次的任务简报写明“修复前需要进行根因调查”，但建议状态仍是 ready-for-agent。只有规格获批后，/go 和 /board 才会将议题计为 Ready，因此 #242 虽位于 Ready，却没有任何东西可以据此构建。
   • ready-for-agent — 根据 agent-brief-template.md 编写并发布 Agent 任务简报。任务简报是执行约定；原始正文和讨论串仅作上下文参考。
   • ready-for-human — 使用相同的简报结构，另加一行说明为何不能委派（需要判断、外部访问权限、设计决策或手动测试）。
   • needs-info — 发布分类记录：先写明目前已确认的内容，再向报告者提出具体且可回答的问题（绝不要只说“请提供更多信息”）。
   • wontfix — 关闭议题，并根据原因选择相应评论：
     • 已实现： 根据步骤 1 中取得的证据，指出该行为的实现位置。不要写入 .out-of-scope/——该知识库记录的是被否决的请求，将已实现的功能记在那里会污染未来的去重检查。
     • 否决的错误报告： 礼貌说明原因，然后关闭。
     • 否决的功能增强请求： 在 .out-of-scope/ 中创建或更新该概念对应的文件（规则见下文），在关闭评论中附上链接，然后关闭。
   • 保持 needs-triage — 添加该标签；只有在有值得记录的阶段性进展时才发表评论。

   完成条件： 议题上恰好有一个类别标签和一个状态标签，并已发布所有必需的评论。

.out-of-scope/ 知识库

每个概念一个文件，采用 kebab-case 命名（plugin-system.md），绝不按问题分别建文件——重复请求应追加到现有文件的先前请求列表中。每个文件包含：概念名称标题、决定、长期有效的理由（项目范围、架构约束、经过权衡的取舍——绝不能写“目前没时间”，这属于延期而非拒绝），以及一个 Prior requests 列表，链接到提出过请求的每个 issue。用朴素的文字撰写，让未来的维护者能够据此采取行动。如果用户推翻先前的拒绝，删除或改写该文件，并按常规流程对新 issue 进行分诊。

直接更改状态

当用户点名某个 issue 及其目标状态（“将 #42 移至 ready-for-agent”）时，这是一个决定，而不是分诊请求——可跳过调查／验证主张／提出建议的流程（步骤 1–3），但仍须遵守以下防护措施：

1. 准确复述要进行的更改——标签编辑、任何评论，以及是否会关闭 issue——并在操作跟踪器前征得用户同意。
2. 如果要直接跳转到 ready-for-agent，提议使用 agent-brief-template.md 撰写简报；缺少简报的 agent-ready issue 会给下一个 Agent 设下陷阱。