xinetzone/SpecWeave / .agents/skills/ci-run-failure-triage
ci-run-failure-triage
VerifiedGitHub Actions 运行/作业失败(CI 红了、跑绿)的取证与闭环修复:从 run/job URL 或一句『CI 挂了』出发,用 gh 取失败 job 与失败日志、在落盘日志里 grep 出真实红项、本地复现同一门禁、区分真失败与本机环境伪失败、只修内容而不削弱门禁、推送后观察新 run 转绿才宣称解决。当用户给出 actions/runs/.../job/... 链接,或说『帮我把 CI 修好/跑绿』『这个 job 为什么失败』『流水线红了』『Actions 报错』『提交后 CI 挂了』『本地绿了远端还红』时,必须使用此技能。不要靠翻网页日志或读 run 标题猜测——本技能封装失败定位、伪失败甄别与转绿验收三段纪律。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.2 KB |
| references/case-20261111.md | markdown | 5.0 KB |
| references/triage-recipes.md | markdown | 4.4 KB |
references/case-20261111.md
View on GitHub# 案例:awesome-okf 规模数字漂移导致的 CI 转绿
> 本案例是 [SKILL.md](../SKILL.md) 六步工作流的完整实证。所有数字与命令均来自 2026-11-11 的实际执行。
## 一、现场
| 项 | 值 |
|---|---|
| 仓库 | `awesome-flexloop/awesome-okf` |
| run | `42946656373`(`push` → `main`) |
| job | `130280975401` · `Quality gates (utf8 / toctrees / bundles / assetbaseline / redline / actionlint)` |
| 触发提交 | `b7bfcdce docs(okf): add cnblogs-publish-skill bundle` |
| 其余 job | `Build (main/dispatch)`、`Build (PR)`、`Deploy to GitHub Pages` 均为 `skipped` |
## 二、红项原文
`--log-failed` 输出 91.0 KB / 534 行并落盘。在落盘文件上按 `✗|::error|exit code` 定位到:
```
✗ 校验失败:2 项
- [规模数字矛盾] doc/index.md: 出现 [731],与总索引 732 不一致;须同步为 732 或改为量级表述
- [规模数字矛盾] README.md: 出现 [729],与总索引 732 不一致;须同步为 732 或改为量级表述
Process completed with exit code 1.
```
同一次输出里,前三个门禁已经通过:
```
UTF-8 检查通过: 13219 个文件均为有效 UTF-8。
toctree 检查通过: 全部 index.md 引用有效,所有内容文档均可达。
bundles 总索引对账通过: 9 域 / 64 组 / 732 束,frontmatter、计数行、节标题、分组表、toctree 五面一致。
```
> 关键信号:**总索引自身是自洽的(732)**,红的是「对外声明面」与它的对账。这直接把修复范围锁定在 README 与 doc/index,而不是目录树或 toctree。
## 三、本地复现
```bash
cd projects/awesome-okf-xs
python scripts/check-bundles-index.py # 9 域 / 64 组 / 732 束,退出码 0
python scripts/check-asset-baseline.py # ✗ 校验失败:2 项,退出码 1
```
条目文字与远端逐字一致 → 判定为真失败·内容类。
## 四、根因
`b7bfcdce` 新增 3 个 bundle(jishu 域),只同步了 `doc/bundles/index.md` 的 frontmatter 与五面计数,
未同步两个人类可读声明面:
- `README.md`:5 处 `729`(shields badge、概述句、`当前实际值` 行、清单提示、九域表合计行);
- `doc/index.md`:2 处 `731`(首段与「关于知识包」段)。
同时 README 九域表的 `技术(jishu)` 行写着 `528`,而总索引 jishu 节是 `537`——即使把合计行改成 732,
该表也会自相矛盾(各域之和 ≠ 合计)。
## 五、修复
| 文件 | 旧值 → 新值 | 处数 |
|---|---|---|
| `README.md` | badge `Bundles-729` → `Bundles-732` | 1 |
| `README.md` | `**729 个知识包、9 大学科域、64 个分组**` → `732` | 1 |
| `README.md` | `当前实际值:**729 束 / 64 组 / 9 域**` → `732` | 1 |
| `README.md` | `完整 729 束清单` → `732` | 1 |
| `README.md` | 九域表 `技术(jishu)` 行 `528` → `537` | 1 |
| `README.md` | 九域表 `**合计**` 行 `729` → `732` | 1 |
| `doc/index.md` | 首段 `731 个知识包` → `732` | 1 |
| `doc/index.md` | `**731 个知识包**` → `732` | 1 |
提交:`3c5dd938 fix(okf): 同步库规模数字至 732 束(README 729 / doc/index 731 漂移)`。
## 六、修复前后门禁对照
| 门禁 | 修复前 | 修复后 |
|---|---|---|
| `check-utf8.py` | 通过(13219 文件) | 通过(13233 文件) |
| `check-toctrees.py` | 通过 | 通过 |
| `check-bundles-index.py` | 通过(732 束) | 通过(732 束) |
| `check-asset-baseline.py` | **失败 2 项** | 通过(残差 `+0`) |
| `check-asset-baseline.py --self-test` | — | 13 项全 PASS |
| `pytest tests/unit/test_no_future_annotations.py` | — | 12 passed |
## 七、一处必须记录的伪失败
本地跑 `pytest tests/unit` 时 `test_doc_parallel_extensions_okf.py::test_target_exts_load` 失败,
报 `sphinx_tippy` 未加载。
判定为**伪失败**,依据:
1. 失败 job 的 steps 只执行 `test_no_future_annotations.py`,不含该文件;
2. 本机未安装 `sphinx_tippy`,属环境差异;
3. `.github/workflows/gates-selftest.yml` 的 `on.paths` 不含文档路径,本次推送不会触发它。
因此不修改该测试、不补依赖、不纳入本次修复范围,但在交付说明里如实登记。
## 八、转绿验收
| 项 | 值 |
|---|---|
| 新 run | `42950774571`(`headSha: 3c5dd938`) |
| `Quality gates (...)` job | `success` |
| `Build (main/dispatch)` | 转 `in_progress`(说明质量门已放行,进入构建阶段) |
至此才可表述为「CI 已修复」。
## 九、可迁移结论
1. **多面声明的一致性门禁,报错会同时给出「真源值」与「违规值」**——先读真源值,再决定改哪一侧;
2. **同一文件里的多处声明必须同批改**,只改 badge 不改合计行会让门禁继续红;
3. **表格的「合计」行与分域行必须一起改**,否则得到一张自相矛盾的表,即使门禁不再报错;
4. **本地红项要先对照 workflow 的 `run:` 行**,再决定是否纳入范围;
5. **门禁已存在时,预防措施写「已有门禁覆盖」并指名是哪条检查**,不新增第二层同类门禁。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |