polish-batch

Polish 批次

三种模式分别运行——capture、dispatch、verify——避免手动 QA 演变成现场逐项指导。

规则

• Capture ≠ fix。 在 capture 模式下，不得更改产品代码、配置、文案或资源。只填写问题清单行、Held 备注和辅助 QA 截图。切勿「既然都在这里了」就顺手修掉细节问题。
• 零署名：提交、PR、问题评论、发行说明、生成的文档、设置或代码注释中，绝不添加或保留共同作者、AI 或工具署名。
• 仅限外观范围。 细节问题必须是纯视觉或文本表层修正，不得更改行为、数据或任何接口（函数签名、API 结构、路由、事件、架构、prop 契约）。涉及上述内容的都不是细节问题——应作为一个切片送回 /to-tickets；如果是 Agent 已经声称完成的工作中存在的 Bug，则转到其问题下的 /qa-escape。任何试图把行为变更说成「只是一个小修复」的做法都是停止信号：指出问题，拒绝将其记录为细节问题，并转交处理。
• 某个页面偏离其设计源，是 /pixel-audit 的工作。 问题清单用于汇总零散的细节问题；必须系统性匹配 Figma 节点或参考屏幕的页面，应转到 /pixel-audit——即使请求写的是「polish」也一样。
• Dispatch 阶段不得重构或顺带更改其他内容。 每一项都必须独立修复，并且一眼看上去就明显正确；否则就不是细节问题。不得清理附近代码、重命名或「顺便改进一下」。
• 所有地方都要使用 Project Matrix 中完整的 PROJECT-CODE；绝不要把一个项目的约定、令牌或组件混用到另一个项目中。
• 不确定某个细节问题属于哪个项目 → 询问；用户不在线 → 使用最可能的代码，并在末尾加上 ?，列入 Needs user。PROJECT-CODE 确认前，绝不丢弃已报告的问题，也不得派发处理。
• 没有 Project Matrix（独立的单仓库安装）→ 从仓库名称推导一个代码（大写并以连字符分隔），并始终一致地使用。
• 只有用户明确同意后才能开始 Dispatch；在此之前，继续 capture。 不得自行从 capture 进入 dispatch，也不得自行从 verify 进入 ship。Verify 结束后，建议使用 /code-review，然后使用 /commit-push-close 或 /commit-push-pr，并停止。
• 重新打开的行要保留。 验证未通过的行要恢复为 open（标记为 reopened），并带入下一轮 capture/dispatch。任何内容都不能悄无声息地丢弃。
• 子 Agent：独立工作自动派发到本地 lane——绝不使用云端 Agent；派发时公布 lane 数量，并在每个 lane 完成时报告。Lane 可以承担派发任务；主会话保留合并和最终判断的职责。
• 每次阶段转换都要输出 Stage / Found / Next / Needs user——每个字段单独一行。

问题清单文件

每个规格文件对应一份问题清单，路径为 <artifacts-root>/specs/qa/<SPEC-ID>-punchlist.md。确定 <artifacts-root>：如果存在 *.code-workspace 目录，就使用该目录；否则使用当前上下文的根目录（仓库根目录中的 GLOSSARY-MAP.md；旧版 CONTEXT-MAP.md）；如果都没有，则使用仓库根目录。

<SPEC-ID> 是规格（PRD）/父级问题标识符（例如 SPEC-142）。没有规格 → 按日期命名：specs/qa/qa-YYYY-MM-DD-punchlist.md；绝不要为了给文件命名而虚构一个跟踪器父级。

一个 Markdown 表格：

# Punch List — <SPEC-ID>

Zero attribution: never add or leave co-author, AI, or tool attribution in any output.

| # | PROJECT-CODE | Where | Wrong → Right | Shot | Status |
| - | ------------ | ----- | ------------- | ---- | ------ |
| 1 | ADMIN-WEB | Settings › Billing header | "Recieve invoices" → "Receive invoices" | shots/admin-web-01.png | open |
| 2 | API-SVC | 429 response `message` field | "To many requests" → "Too many requests" | (no shot — text only) | open |

• 位置 — 准确的界面位置：屏幕 › 区域 › 元素，或响应字段 / 字符串键。
• 错误 → 正确 — 用一行描述当前内容 → 预期内容；这是 verify 的验收标准。
• 截图 — specs/qa/shots/ 下的路径，或字面文本 (no shot — text only)；缺少截图绝不能阻止 capture。
• 状态 — open → dispatched → verified 或 reopened。

模式

仅运行请求的模式；默认模式为 capture。加载该模式的流程和输出格式，不要加载其他模式：

• capture — references/capture.md：仅追加 QA 工件。
• dispatch — references/dispatch.md：收到明确的新 dispatch 指令后，将有界修复分组，并记录变更前的控制台证据。
• verify — references/verify.md：任务反馈后，对比限定范围内的差异和服务结果；缺少证明的项目仍保持待处理状态。

跨仓库

某个 spec 的所有细节问题都集中记录在其唯一的待办清单中——绝不为每个仓库分别创建文件——而 dispatch 则按 PROJECT-CODE 分开：每个涉及的项目一个文件、一个 dispatch 任务。

输出

输出所选模式在其参考文件中规定的更新内容。Verify 以 1–3 条建议的后续技能建议结尾，然后停止；绝不开始交付。

完成标准

• 待办清单位于 <artifacts-root>/specs/qa/<SPEC-ID>-punchlist.md（或按日期命名）；每个报告的问题都必须作为一行、标记为 Held，或明确转交处理
• capture：初始与最终状态及差异表明本次运行仅写入 QA 工件；预先存在的变更保持完整
• dispatch：更新内容引用用户的明确指令；每个交接行的 Status 均为 dispatched
• verify：每个已 dispatch 的行均为 verified 并附带证据、因失败而标记为 reopened，或标记为 dispatched 并注明缺少的检查项