ci-triage

CI 分诊

在逐一追查所有失败之前，先找到最小且可信的信号。

流程

1. 记录失败的检查

列出每条失败的命令或 CI 作业，并注明：

• 检查名称。
• 失败摘要。
• 相关日志摘录。
• 检查是在当前分支、基分支还是两个分支上运行的。

将跳过的检查、基础设施故障和代码故障分别列出。

2. 在本地复现成本最低的信号

复现范围最窄、且能区分疑似原因的失败命令或探测。不要把格式检查、类型检查和完整测试套件作为必须依次执行的步骤。如果编译或设置失败导致相关测试无法运行，应先解决该问题；无关的 lint 失败不必阻碍对独立测试失败的诊断。

如果失败涉及的依赖项或受影响边界有此需要，再扩大验证范围。

3. 必要时与基分支比较

如果失败可能是此前就存在的，或由环境导致，请在基分支或已知正常的提交上运行相同的检查并进行比较。

对每项失败进行分类：

• 由此更改引入 — 立即修复。
• 此前就存在 — 提供证据并报告；除非有人要求，否则不要扩大范围。
• 基础设施或环境问题 — 报告证据，并指出需要重新运行的内容或所需访问权限。
• 未知 — 继续调查，直至能够分类或明确指出阻碍。

4. 实施有限范围的修复

获准修复时，只修复风险低、影响局部、属于机械性调整且明确由当前更改导致的问题。仅要求诊断的请求应保持只读；对任何会产生副作用的写入操作或命令应用 /persistent-side-effects。符合条件的修复包括：

• 格式化工具或 linter 的自动修复。
• 缺失的导入、仅用于类型的导入或明显的导入顺序问题。
• 已知且预期会生成类型或生成产物的命令所产生的更新。
• 预期行为已明确时，对测试或夹具进行拼写错误级别的更新。
• 仅影响验证工具链的命令／配置不匹配。

不要借助 CI 分诊来设计新行为、修改产品逻辑以通过测试、进行大范围重构，或猜测产品缺陷的根本原因。此类问题应交由以下流程处理：

• 如果修复需要代码更改计划或非机械性实现，请使用 /implement-plan。
• 如果失败暴露了尚不清楚原因的产品／运行时行为缺陷，请使用 /diagnose-bug。

实施任何有限范围的修复后，重新运行能够验证该修复的最窄范围检查。

5. 报告当前状态

报告以下内容：

• 哪些失败由当前更改导致。
• 哪些失败此前就存在或由环境导致，并附上证据。
• 实施了哪些有限范围的修复。
• 哪些失败需要交由 /implement-plan 或 /diagnose-bug 处理。
• 重新运行了哪些命令及其结果。
• 任何仍然存在的阻碍，以及下一步所需的确切产物。

完成标准

当每项失败检查都已分类，获准的安全有限范围修复已实施并重新运行（或针对仅要求诊断的工作提出修复方案），需要实现或诊断缺陷的失败已附证据并移交处理，且其余失败均有证据表明是此前就存在、由环境导致、偶发或受阻时，CI 分诊即告完成。