@namewta/speculo 0.1.21 → 0.2.0

package/template/vendor/matt-pocock/engineering/tdd/tests.md

@@ -0,0 +1,77 @@
+# 好的测试与坏的测试
+
+## 好的测试
+
+**集成风格**：通过真实接口测试，而非 mock 内部部件。
+
+```typescript
+// 好：测试可观察的行为
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+特征：
+
+- 测试用户/调用方关心的行为
+- 仅使用公共 API
+- 经受住内部重构
+- 描述 WHAT（做什么），而非 HOW（怎么做）
+- 每个测试一个逻辑断言
+
+## 坏的测试
+
+**实现细节测试**：与内部结构耦合。
+
+```typescript
+// 坏：测试实现细节
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+危险信号：
+
+- Mock 内部协作者
+- 测试私有方法
+- 断言调用次数/顺序
+- 重构时测试失败但没有行为变化
+- 测试名称描述 HOW 而非 WHAT
+- 通过外部手段而非接口进行验证
+
+```typescript
+// 坏：绕过接口进行验证
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// 好：通过接口进行验证
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**同义反复测试**：预期值重述了实现，因此测试在构造上就通过了。
+
+```typescript
+// 坏：预期值以与代码计算方式相同的方式重新计算
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// 好：预期值是独立的、已知的字面量
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

package/template/vendor/matt-pocock/engineering/to-spec/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: to-spec
+description: "将当前对话转化为 spec 并发布到项目 issue tracker —— 无需访谈，仅综合你们已讨论过的内容。"
+disable-model-invocation: true
+---
+
+此技能读取当前对话上下文和代码库理解，产出一份 spec（你可能也称之为 PRD）。不要访谈用户 —— 仅综合你已经知道的内容。
+
+Issue tracker 和 triage 标签词汇表应已提供给你 —— 如果没有，运行 `/setup-matt-pocock-skills`。
+
+## 流程
+
+1. 探索仓库以了解代码库的当前状态（如果尚未这样做）。在整个 spec 中使用项目的领域词汇表，并尊重所涉及区域的任何 ADR。
+
+2. 草拟你将用于测试该功能的接缝（seam）。优先使用现有接缝而不是新建。使用尽可能高层的接缝。如果需要新接缝，在尽可能高的层级提出。代码库中的接缝越少越好 —— 理想数量是 1 个。
+
+与用户确认这些接缝是否符合他们的期望。
+
+3. 使用以下模板编写 spec，然后发布到项目 issue tracker。应用 `ready-for-agent` triage 标签 —— 无需额外 triage。
+
+<spec-template>
+
+## 问题陈述
+
+从用户视角描述用户面临的问题。
+
+## 解决方案
+
+从用户视角描述问题的解决方案。
+
+## 用户故事
+
+一个详细的、编号的用户故事列表。每个用户故事格式为：
+
+1. 作为 <角色>，我希望 <功能>，以便 <收益>
+
+<user-story-example>
+1. 作为手机银行客户，我希望查看账户余额，以便做出更明智的消费决策
+</user-story-example>
+
+用户故事列表应极其详尽，涵盖该功能的所有方面。
+
+## 实现决策
+
+已做出的实现决策列表。可包含：
+
+- 将构建/修改的模块
+- 这些模块将被修改的接口
+- 开发者的技术澄清
+- 架构决策
+- Schema 变更
+- API 契约
+- 具体交互
+
+不要包含具体文件路径或代码片段。它们可能很快过时。
+
+例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联在相关决策中，并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+
+## 测试决策
+
+已做出的测试决策列表。包含：
+
+- 什么构成好测试的描述（只测试外部行为，不测试实现细节）
+- 哪些模块将被测试
+- 测试的先例（即代码库中类似类型的测试）
+
+## 超出范围
+
+描述此 spec 超出范围的内容。
+
+## 补充说明
+
+关于该功能的任何补充说明。
+
+</spec-template>

package/template/vendor/matt-pocock/engineering/to-tickets/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: to-tickets
+description: "将计划、spec 或当前对话拆分为一组曳光弹式 tickets，每个 ticket 声明其阻塞边，发布到已配置的 tracker —— 对于本地文件，边以文本形式呈现；对于真实 tracker，使用原生阻塞链接。"
+disable-model-invocation: true
+---
+
+# 转为 Tickets
+
+将计划、spec 或对话拆分为一组 **tickets** —— 曳光弹式垂直切片，每个 ticket 声明**阻塞**它的那些 tickets。
+
+Issue tracker 和 triage 标签词汇表应已提供给你 —— 如果没有，运行 `/setup-matt-pocock-skills`。
+
+## 流程
+
+### 1. 收集上下文
+
+基于对话上下文中已有的内容进行工作。如果用户将某个引用（spec 路径、issue 编号或 URL）作为参数传入，拉取它并读取其完整正文和评论。
+
+### 2. 探索代码库（可选）
+
+如果尚未探索代码库，进行探索以了解代码的当前状态。Ticket 标题和描述应使用项目的领域词汇表，并尊重所涉及区域的 ADR。
+
+寻找预重构（prefactor）的机会，使实现更简单。"让变更变容易，然后做容易的变更。"
+
+### 3. 草拟垂直切片
+
+将工作拆分为**曳光弹** tickets。
+
+<vertical-slice-rules>
+
+- 每个切片横向切穿每一层（schema、API、UI、测试），是一条窄但**完整**的路径 —— 是垂直切片，不是某一层的水平切片
+- 一个完成的切片可以独立演示或验证
+- 每个切片的大小适配单个全新上下文窗口
+- 任何预重构应最先完成
+
+</vertical-slice-rules>
+
+为每个 ticket 标注其**阻塞边** —— 即必须在它开始之前完成的其他 tickets。没有阻塞边的 ticket 可以立即开始。
+
+**宽重构是垂直切片的例外。** **宽重构**是指一个机械性变更 —— 重命名字段、修改共享符号的类型 —— 其**影响范围**辐射整个代码库，因此单次编辑会破坏数千个调用点，任何垂直切片都无法以绿色状态落地。不要强行将其塞入曳光弹；应将其排序为**扩展-收缩**序列。首先扩展：在旧形式旁边添加新形式，使一切不中断。然后按影响范围分批迁移调用点（按包、按目录），每批是一个由扩展阶段阻塞的独立 ticket，保持 CI 逐批绿色，因为旧形式仍然存在。最后收缩：当没有调用方残留时删除旧形式，由一个由所有迁移批次阻塞的 ticket 负责。当连批次本身都无法独立保持绿色时，保持排序不变，但让它们共享一个集成分支，所有批次共同阻塞一个最终的集成验证 ticket —— 绿色仅在该处得到承诺。
+
+### 4. 与用户核对
+
+以编号列表形式呈现提议的拆分方案。对于每个 ticket，展示：
+
+- **标题**：简短的描述性名称
+- **被阻塞于**：必须首先完成的其他 tickets（如有）
+- **它交付什么**：此 ticket 使哪些端到端行为可用
+
+询问用户：
+
+- 粒度是否合适？（太粗 / 太细）
+- 阻塞边是否正确 —— 每个 ticket 是否只依赖于真正阻碍它的 tickets？
+- 是否有 tickets 应合并或进一步拆分？
+
+迭代直到用户批准拆分方案。
+
+### 5. 将 tickets 发布到已配置的 tracker
+
+发布已批准的 tickets。**如何**发布取决于 `/setup-matt-pocock-skills` 配置的 tracker —— 无论哪种方式 tickets 都相同，只有阻塞边的形式不同：
+
+- **本地文件** → 在仓库根目录写入一个 `tickets.md`，按依赖顺序排列所有 tickets（阻塞者在前），每个 ticket 的"被阻塞于"列出它所依赖的标题。使用下面的文件模板。
+- **真实 issue tracker（GitHub、Linear 等）** → 按依赖顺序（阻塞者在前）为每个 ticket 发布一个 issue，以便每个 ticket 的阻塞边可以引用真实标识符。使用平台的原生阻塞/子 issue 关系（如果有的话）；否则将每个 ticket 的"被阻塞于"设置为阻塞它的 issues。除非另有指示，应用 `ready-for-agent` triage 标签 —— 这些 tickets 在构造上就是 agent 可领取的。
+
+不要关闭或修改任何父 issue。
+
+<tickets-file-template>
+
+# Tickets：<工作的简短名称>
+
+一句话总结这些 tickets 构建的内容。如果有来源 spec，引用它。
+
+从**前沿**开始工作：找到所有阻塞边已完成的 tickets。对于纯线性链，这意味着从上到下。
+
+## <Ticket 标题>
+
+**要构建什么：** 此 ticket 使哪些端到端行为可用，从用户视角 —— 不是逐层实现清单。
+
+**被阻塞于：** 阻碍此 ticket 的 tickets 标题，或"无 —— 可立即开始"。
+
+- [ ] 验收标准 1
+- [ ] 验收标准 2
+
+## <Ticket 标题>
+
+...
+
+</tickets-file-template>
+
+<issue-template>
+
+## 父 issue
+
+对 tracker 上父 issue 的引用（如果来源是已有 issue，否则省略此节）。
+
+## 要构建什么
+
+此 ticket 使哪些端到端行为可用，从用户视角 —— 不是逐层实现。
+
+## 验收标准
+
+- [ ] 标准 1
+- [ ] 标准 2
+
+## 被阻塞于
+
+- 对每个阻塞 ticket 的引用，或"无 —— 可立即开始"。
+
+</issue-template>
+
+无论哪种形式，避免具体文件路径或代码片段 —— 它们会很快过时。例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+
+使用 `/implement` 逐个处理前沿上的 tickets，ticket 之间清空上下文。

package/template/vendor/matt-pocock/engineering/triage/AGENT-BRIEF.md

@@ -0,0 +1,204 @@
+# 编写 Agent 简报
+
+Agent 简报是一段结构化的评论，在 issue 或 PR 进入 `ready-for-agent` 状态时发布到 GitHub issue 或 PR 上。它是离线 Agent 将依据的权威规范。原始正文和讨论是上下文 — Agent 简报是契约。
+
+简报陈述了 **Agent 应该做什么**，这延伸到两种处理面：对于 issue，是从零开始构建变更；对于 PR，是对*现有 diff* 的剩余工作 — 完成它、填补缺口、处理审查意见。无论哪种处理面，原则相同；下面的 PR 示例展示了差异。
+
+## 原则
+
+### 持久性优先于精确性
+
+Issue 可能在 `ready-for-agent` 状态下停留数天或数周。代码库在此期间会发生变化。编写简报时要确保即使在文件被重命名、移动或重构后仍然有用。
+
+- **要**描述接口、类型和行为契约
+- **要**命名 Agent 应该查找或修改的特定类型、函数签名或配置形态
+- **不要**引用文件路径 — 它们会过时
+- **不要**引用行号
+- **不要**假设当前实现结构将保持不变
+
+### 行为性，而非过程性
+
+描述系统**应该做什么**，而非**如何**实现。Agent 将重新探索代码库并做出自己的实现决策。
+
+- **好的：** "`SkillConfig` 类型应该接受一个可选的 `schedule` 字段，类型为 `CronExpression`"
+- **坏的：** "打开 src/types/skill.ts 并在第 42 行添加一个 schedule 字段"
+- **好的：** "当用户不带参数运行 `/triage` 时，他们应该看到一个需要关注的 issue 摘要"
+- **坏的：** "在主处理函数中添加一个 switch 语句"
+
+### 完整的验收标准
+
+Agent 需要知道何时完成。每个 Agent 简报必须有具体的、可测试的验收标准。每个标准应可独立验证。
+
+- **好的：** "运行 `gh issue list --label needs-triage` 返回已经过初始分类的 issue"
+- **坏的：** "分类应该正常工作"
+
+### 明确的范围边界
+
+说明哪些内容不在范围内。这可以防止 Agent 画蛇添足或对相邻功能做出假设。
+
+## 模板
+
+```markdown
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** 需要完成的事项的一句话描述
+
+**Current behavior:**
+描述当前发生的情况。对于 bug，这是有问题的行为。
+对于增强，这是该功能建立在其上的现状。
+
+**Desired behavior:**
+描述 Agent 工作完成后应该发生的情况。
+具体说明边界情况和错误条件。
+
+**Key interfaces:**
+- `TypeName` — 需要改变什么以及为什么
+- `functionName()` 返回类型 — 当前返回什么以及应该返回什么
+- 配置形态 — 任何需要的新配置选项
+
+**Acceptance criteria:**
+- [ ] 具体的、可测试的标准 1
+- [ ] 具体的、可测试的标准 2
+- [ ] 具体的、可测试的标准 3
+
+**Out of scope:**
+- 不应在此 issue 中改变或处理的事项
+- 看似相关但独立的相邻功能
+```
+
+## 示例
+
+### 好的 Agent 简报（bug）
+
+```markdown
+## Agent Brief
+
+**Category:** bug
+**Summary:** Skill 描述截断在单词中间断开，产生破碎的输出
+
+**Current behavior:**
+当 skill 描述超过 1024 个字符时，它被精确地在 1024 个字符处截断，
+不考虑单词边界。这会产生在单词中间断开的描述
+（例如"confi"）。
+
+**Desired behavior:**
+截断应在 1024 个字符之前的最后一个单词边界处断行，
+并追加"..."以指示截断。
+
+**Key interfaces:**
+- `SkillMetadata` 类型的 `description` 字段 — 不需要类型变更，
+  但填充它的验证/处理逻辑需要尊重单词边界
+- 任何读取 SKILL.md 前置元数据并提取描述的函数
+
+**Acceptance criteria:**
+- [ ] 低于 1024 个字符的描述保持不变
+- [ ] 超过 1024 个字符的描述在 1024 个字符之前的
+      最后一个单词边界处截断
+- [ ] 被截断的描述以"..."结束
+- [ ] 包括"..."的总长度不超过 1024 个字符
+
+**Out of scope:**
+- 更改 1024 个字符的限制本身
+- 多行描述支持
+```
+
+### 好的 Agent 简报（增强）
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** 添加 `.out-of-scope/` 目录支持以跟踪被拒绝的功能请求
+
+**Current behavior:**
+当功能请求被拒绝时，issue 以 `wontfix` 标签和一条评论关闭。
+没有对决策或理由的持久记录。
+未来类似的请求需要维护者回忆或搜索之前的讨论。
+
+**Desired behavior:**
+被拒绝的功能请求应记录在 `.out-of-scope/<concept>.md`
+文件中，捕获决策、理由以及所有请求该功能的 issue 链接。
+在分类新 issue 时，应检查这些文件以查找匹配项。
+
+**Key interfaces:**
+- `.out-of-scope/` 中的 Markdown 文件格式 — 每个文件应有
+  一个 `# Concept Name` 标题、一个 `**Decision:**` 行、一个 `**Reason:**` 行
+  以及一个包含 issue 链接的 `**Prior requests:**` 列表
+- 分类工作流应尽早读取所有 `.out-of-scope/*.md` 文件
+  并通过概念相似性将新 issue 与它们匹配
+
+**Acceptance criteria:**
+- [ ] 以 wontfix 关闭功能请求会创建/更新 `.out-of-scope/` 中的文件
+- [ ] 文件包含决策、理由以及指向已关闭 issue 的链接
+- [ ] 如果匹配的 `.out-of-scope/` 文件已存在，新 issue 被追加到
+      其"Prior requests"列表中，而非创建重复文件
+- [ ] 分类期间，现有 `.out-of-scope/` 文件被检查并在新 issue
+      匹配之前的拒绝时被呈现出来
+
+**Out of scope:**
+- 自动匹配（人工确认匹配）
+- 重新打开之前被拒绝的功能
+- Bug 报告（只有增强的拒绝才进入 `.out-of-scope/`）
+```
+
+### 好的 Agent 简报（PR）
+
+对于 PR，"Current behavior" 描述 diff 的状态，简报要求 Agent 完成或修复它，而非从零构建。
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** 完成贡献者针对 `triage list` 的 `--json` 输出标志
+
+**Current behavior:**
+该 PR 添加了一个 `--json` 标志，将 issue 列表序列化为 JSON。正常
+路径工作正常，diff 匹配项目的命令结构。还有两个缺口
+未完成：错误仍然以人类文本（非 JSON）打印，且新标志
+没有测试覆盖。
+
+**Desired behavior:**
+使用 `--json` 时，所有输出 — 包括错误 — 是 stdout 上的格式良好的 JSON，
+且命令的退出代码不变。当标志缺失时，现有的人类可读输出
+不受影响。
+
+**Key interfaces:**
+- 命令的错误路径在 `--json` 下应发出 `{ "error": string }`
+  而非纯文本错误
+- 复用 PR 中已添加的现有序列化器；不要引入第二个
+
+**Acceptance criteria:**
+- [ ] `triage list --json` 对成功和错误情况都发出有效的 JSON
+- [ ] 退出代码匹配非 JSON 命令
+- [ ] 测试覆盖 `--json` 成功输出和一个错误情况
+- [ ] 默认（非 JSON）输出逐字节不变
+
+**Out of scope:**
+- 为任何其他命令添加 `--json`
+- 更改 PR 中已定义的 JSON 成功负载的形状
+```
+
+### 坏的 Agent 简报
+
+```markdown
+## Agent Brief
+
+**Summary:** 修复分类 bug
+
+**What to do:**
+分类功能坏了。查看主文件并修复它。
+大约在第 150 行的函数有问题。
+
+**Files to change:**
+- src/triage/handler.ts (第 150 行)
+- src/types.ts (第 42 行)
+```
+
+这之所以坏，是因为：
+- 没有类别
+- 模糊的描述（"分类功能坏了"）
+- 引用了会过时的文件路径和行号
+- 没有验收标准
+- 没有范围边界
+- 没有当前行为 vs 期望行为的描述

package/template/vendor/matt-pocock/engineering/triage/OUT-OF-SCOPE.md

@@ -0,0 +1,104 @@
+# 范围外知识库
+
+仓库中的 `.out-of-scope/` 目录存储被拒绝功能请求的持久记录。它有两个目的：
+
+1. **机构记忆** — 为什么一个功能被拒绝，这样理由不会随 issue 关闭而丢失
+2. **去重** — 当新 issue 与之前的拒绝匹配时，该 skill 可以呈现之前的决策而非重新讨论
+
+## 目录结构
+
+```
+.out-of-scope/
+├── dark-mode.md
+├── plugin-system.md
+└── graphql-api.md
+```
+
+每个**概念**一个文件，而非每个 issue 一个文件。请求同一功能的多个 issue 归入同一个文件。
+
+## 文件格式
+
+文件应以轻松、可读的风格编写 — 更像一份简短的设计文档，而非数据库条目。使用段落、代码示例和实例让理由清晰并对初次遇到它的人有用。
+
+```markdown
+# Dark Mode
+
+此项目不支持深色模式或面向用户的主题化。
+
+## Why this is out of scope
+
+渲染管线假定在 `ThemeConfig` 中定义单一调色板。
+支持多主题将需要：
+
+- 包装整个组件树的主题上下文提供者
+- 每个组件的主题感知样式解析
+- 用户主题偏好的持久层
+
+这是一个重大的架构变更，不符合项目对内容创作的聚焦。
+主题化是下游消费者（嵌入或再分发输出的消费者）的关注点。
+
+```ts
+// 当前的 ThemeConfig 接口不是为运行时切换而设计的：
+interface ThemeConfig {
+  colors: ColorPalette; // 单一调色板，在构建时解析
+  fonts: FontStack;
+}
+```
+
+## Prior requests
+
+- #42 — "添加深色模式支持"
+- #87 — "用于无障碍的夜间主题"
+- #134 — "深色主题选项"
+```
+
+### 文件命名
+
+使用简短的、描述性的 kebab-case 名称来表示概念：`dark-mode.md`、`plugin-system.md`、`graphql-api.md`。名称应足够可辨识，使浏览目录的人无需打开文件就能理解被拒绝的是什么。
+
+### 编写理由
+
+理由应是实质性的 — 不是"我们不想要这个"而是为什么。好的理由引用：
+
+- 项目范围或理念（"本项目聚焦于 X；主题化是下游关注点"）
+- 技术约束（"支持这个将需要 Y，这与我们的 Z 架构冲突"）
+- 战略决策（"我们选择使用 A 而不是 B，因为……"）
+
+理由应是持久的。避免引用临时情况（"我们目前太忙了"）— 那些不是真正的拒绝，而是推迟。
+
+## 何时检查 `.out-of-scope/`
+
+在分类期间（第 1 步：收集上下文），读取 `.out-of-scope/` 中的所有文件。在评估新 issue 时：
+
+- 检查请求是否匹配现有的范围外概念
+- 匹配基于概念相似性，而非关键词 — "night theme" 匹配 `dark-mode.md`
+- 如果存在匹配，将其呈现给维护者："这与 `.out-of-scope/dark-mode.md` 相似 — 我们之前因为 [理由] 拒绝了这个。你仍然有同样的感觉吗？"
+
+维护者可能：
+
+- **确认** — 新 issue 被添加到现有文件的"Prior requests"列表中，然后关闭
+- **重新考虑** — 范围外文件被删除或更新，issue 进入正常分类流程
+- **不同意** — 这些 issue 相关但不同，继续正常分类
+
+## 何时写入 `.out-of-scope/`
+
+仅当**增强**（非 bug）被*拒绝*为 `wontfix` 时。这也适用于增强 PR，就像适用于 issue 一样 — 被拒绝的 PR 被记录在这里，这样相同的请求不会以新代码的形式再次出现。
+
+**不要**在某个功能以 `wontfix` 关闭是因为它**已经实现了**的情况下写入这里。那是已构建的功能，不是被拒绝的功能；记录它将用虚假的拒绝污染去重检查。相反，关闭评论指出功能已经存在的位置。
+
+流程：
+
+1. 维护者判断功能请求超出范围
+2. 检查是否已存在匹配的 `.out-of-scope/` 文件
+3. 如果是：将新 issue 追加到"Prior requests"列表
+4. 如果否：创建一个新文件，包含概念名称、决策、理由和第一个先前的请求
+5. 在 issue 上发布一条评论，说明决策并提及 `.out-of-scope/` 文件
+6. 用 `wontfix` 标签关闭 issue
+
+## 更新或删除范围外文件
+
+如果维护者改变了关于之前被拒绝概念的想法：
+
+- 删除 `.out-of-scope/` 文件
+- 该 skill 不需要重新打开旧的 issue — 它们是历史记录
+- 触发重新考虑的新 issue 进入正常分类流程

package/template/vendor/matt-pocock/engineering/triage/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: triage
+description: "将 issues 和外部 PRs 移过 triage 角色状态机 —— 分类、验证、必要时进行质询，并编写 agent 可用的摘要。"
+disable-model-invocation: true
+---
+
+# Triage
+
+将项目 issue tracker 上的 issues 移过一个小型的 triage 角色状态机。
+
+如果本仓库将外部 Pull Request 视为请求渠道（参见 issue-tracker 配置），triage 也涵盖它们：**PR 是附带代码的 issue** —— 相同的角色、相同的状态、相同的状态机，仅有少数标记为"对于 PR"的差异。将裸 `#42` 解析为 issue 或 PR，取决于 tracker 配置。
+
+Triage 期间发布到 issue tracker 的每条评论或 issue **必须**以此声明开头：
+
+```
+> *This was generated by AI during triage.*
+```
+
+## 参考文档
+
+- [AGENT-BRIEF.md](AGENT-BRIEF.md) —— 如何编写持久的 agent 摘要
+- [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` 表示附有 agent 摘要，agent 应对 diff 采取下一步操作；`ready-for-human` 表示可供人工合并。
+
+每个经 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` 并用自然语言描述他们想要什么。解读请求并行动。示例：
+
+- "展示需要我关注的内容"
+- "我们看看 #42"（issue 或 PR）
+- "将 #42 移至 ready-for-agent"
+- "有哪些可供 agents 领取的？"
+
+## 展示需要关注的内容
+
+查询 issue tracker 并按以下三个分组展示，最旧的优先：
+
+1. **未标记** —— 从未经过 triage。
+2. **`needs-triage`** —— 评估进行中。
+3. **自上次 triage 记录以来有报告者活动的 `needs-info`** —— 需要重新评估。
+
+当 PR 在范围内时，将外部 PR 纳入这些分组，并为每行标记 `[PR]` 或 `[issue]`。发现仅展示*外部* PR（tracker 配置定义了谁算外部）—— 协作者进行中的 PR 不是 triage 工作。此过滤器仅用于发现；明确指定的 PR 无论作者是谁都会被 triage。
+
+显示每个分组的数量和每项的一句话摘要。让维护者选择。
+
+## 对特定 issue 或 PR 进行 Triage
+
+1. **收集上下文。** 读取完整的 issue 或 PR（正文、评论、标签、作者、日期；对于 PR，还包括 diff）。解析之前的 triage 记录，以免重复询问已解决的问题。使用项目的领域词汇表探索代码库，尊重所涉及区域的 ADR。针对代码库运行两项检查：(a) **冗余性** —— 按领域概念搜索所请求行为的现有实现（不仅仅是请求的措辞），并报告你查找的位置。如果找到，它是已实现的情况，按 `wontfix` 处理（第 5 步）。(b) **之前的拒绝** —— 读取 `.out-of-scope/*.md` 并找出与此请求类似的任何内容。
+
+2. **建议。** 告诉维护者你的类别和状态建议及理由，加上与请求相关的简要代码库摘要 —— 包括是否已实现。等待指示。
+
+3. **验证声明。** 在任何质询之前，检查声明是否成立。对于 bug，按报告者的步骤复现。对于 PR，确认 diff 做了它声称做的事情 —— checkout 它，运行相关测试或命令。报告结果：已确认（含代码路径）、未通过、或细节不足（强烈的 `needs-info` 信号）。已确认的验证会产生更强的 agent 摘要。
+
+4. **质询（如需要）。** 如果请求需要充实，同时运行 `/grilling` 和 `/domain-modeling` 技能 —— 逐个问题地进行质询，随着决策落地内联更新 `CONTEXT.md`/ADR。
+
+5. **应用结果：**
+   - `ready-for-agent` —— 发布 agent 摘要评论（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。
+   - `ready-for-human` —— 与 agent 摘要结构相同，但注明为何无法委托（判断性决策、外部访问、设计决策、手动测试）。
+   - `needs-info` —— 发布 triage 记录（下方模板）。
+   - `wontfix` —— 关闭，评论取决于*原因*：
+     - **已实现** —— 该变更已存在于代码库中。指出其位置；**不**写入 `.out-of-scope/`（该知识库用于*被拒绝*的请求，而非已构建的请求）。
+     - **被拒绝（bug）** —— 礼貌解释，然后关闭。
+     - **被拒绝（enhancement）** —— 写入 `.out-of-scope/`，在评论中链接它，然后关闭（[OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)）。
+   - `needs-triage` —— 应用角色。如有部分进展，可选评论。
+
+## 快速状态覆盖
+
+如果维护者说"将 #42 移至 ready-for-agent"，信任他们并直接应用角色。确认你即将执行的操作（角色变更、评论、关闭），然后行动。跳过质询。如果在没有质询会话的情况下移至 `ready-for-agent`，询问他们是否需要编写 agent 摘要。
+
+## Needs-info 模板
+
+```markdown
+## Triage Notes
+
+**目前已确认的内容：**
+
+- 要点 1
+- 要点 2
+
+**仍需您提供的信息（@报告者）：**
+
+- 问题 1
+- 问题 2
+```
+
+将质询期间已解决的所有内容记录在"目前已确认"下，以免工作丢失。问题必须具体且可操作，而非"请提供更多信息"。
+
+## 恢复之前的会话
+
+如果 issue 或 PR 上存在之前的 triage 记录，读取它们，检查报告者是否已回答了任何未解决的问题，并在继续之前呈现更新的情况。不要重复询问已解决的问题。