adamayoung/TMDb / .claude/skills/diagnose-ci-failure
diagnose-ci-failure
VerifiedDiagnose a failing CI workflow run (lint, markdown lint, build, or unit tests) — identify which job failed, the cause, and a concrete fix
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
| references/_index.md | markdown | 2.5 KB |
| references/build.md | markdown | 3.4 KB |
| references/lint.md | markdown | 4.9 KB |
| references/linux.md | markdown | 2.7 KB |
| references/markdown.md | markdown | 2.9 KB |
| references/unit-tests.md | markdown | 3.4 KB |
SKILL.md
View on GitHub---
name: diagnose-ci-failure
description: Diagnose a failing CI workflow run (lint, markdown lint, build, or unit tests) — identify which job failed, the cause, and a concrete fix
---
# Diagnose a CI workflow failure
## Overview
The **CI** workflow (`.github/workflows/ci.yml`) gates every PR and the merge to
`main`. Unlike the live-API integration suite, a CI failure is **almost always
caused by the change under review** — a lint violation, a compile warning/error,
a broken unit test, or a Linux-portability gap. Start from the diff, not from
"maybe it's flaky".
CI fans out into six real jobs (plus a `changes` paths-filter job and a `ci`
gate job that only aggregates results): `Lint`, `Lint Markdown`,
`Build and Test` (macOS), `Build (<platform>)` (an iOS/tvOS/watchOS/visionOS
simulator-build matrix), `Build and Test (Linux)`, and `Test (<timezone>)` (a
time-zone matrix re-running the unit suites). The diagnosis differs per job, so
this skill is a **router**: identify the failing job, then follow the matching
reference file for that job's causes, fixes, and local-reproduction command.
> **Wrong suite?** If the **Integration** workflow (the live-API suite from
> `integration.yml`) failed — not a CI job — use `/diagnose-integration-failure`
> instead. It leads with the opposite assumption: a scheduled/live-API failure
> is usually backend or data drift, not your change.
## Agent Behaviour Contract
1. **Identify the failing job first** — `Lint`, `Lint Markdown`, `Build and Test`
(macOS), `Build (<platform>)`, `Build and Test (Linux)`, or
`Test (<timezone>)`. Don't guess the cause before you know the job.
2. **Assume the change caused it.** CI gates the PR; read the diff and tie the
failure to a changed file. Don't open with "transient" or "flaky".
3. **Treat warnings as errors.** Build steps use `-warnings-as-errors` / `--Werror`
— a deprecation or unused-binding warning is a real failure.
4. **Reproduce locally before declaring a fix** using the matching tool (`/lint`,
`/build-for-testing`, `/test`, `make lint-markdown`, `make build-linux`).
5. **Output the three sections** (Summary / Cause / Fix) defined below — concise,
tied to `file:line`.
## Locate the failing run
Use the first that applies:
- A path or run id the caller handed you.
- The current branch's run via the **GitHub MCP** (owner/repo from the `origin`
remote): `mcp__github__actions_list` method `list_workflow_runs`
(`resource_id: ci.yml`, `workflow_runs_filter: { branch: <branch> }`), then
`mcp__github__get_job_logs` (`run_id: <id>`, `failed_only: true`,
`return_content: true`). (`mcp__github__pull_request_read` method
`get_check_runs` also shows which job is red.) **Headless / no MCP:**
`gh run list --workflow CI --branch "$(git branch --show-current)" --limit 1`,
then `gh run view <id> --log-failed`.
- CI pipes build/test output through **xcsift** in `github-actions` format, so
the failing lines are GitHub `::error::` annotations carrying `file:line` —
read those first.
## Quick decision tree
Once you know which job failed:
- **Lint** (`swiftlint --strict` / `swiftformat --lint` / one of the six
`Scripts/*.py` gate steps)?
└─ `references/lint.md` — style/format violations, the Python gates, and the
version-drift gotcha
- **Lint Markdown** (`markdownlint`)?
└─ `references/markdown.md` — README / DocC / `.claude/` / `knowledge/` rules
- **Build and Test** — the **build** step failed?
└─ `references/build.md` — compile errors and `--Werror` warnings
- **Build and Test** — the **test** step failed?
└─ `references/unit-tests.md` — failing `Suite/test`, fixture/model mismatch
- **Build (iOS / tvOS / watchOS / visionOS)** — a simulator matrix build failed?
└─ `references/build.md` — platform-specific API availability; it is
`xcodebuild`, not SwiftPM, so `make build` green does not clear it
- **Build and Test (Linux)** — fails on Linux but passes on macOS?
└─ `references/linux.md` — Apple-only API gating, Foundation differences
- **Test (America/Los_Angeles or Pacific/Auckland)** — the TZ matrix failed?
└─ `references/unit-tests.md` — a date/calendar assertion depending on the
runner's zone; reproduce with `TZ=<zone> make test`
## Triage-first playbook
Symptom → next move:
- **`error: … is unavailable` / `cannot find … in scope`, Linux job only** → `references/linux.md`
- **`warning: … treated as error`** → `references/build.md`
- **`error:` from `swiftc` on macOS build** → `references/build.md`
- **A `Suite/test` recorded a failure / `#expect` failed** → `references/unit-tests.md`
- **Test fails to decode a fixture (`keyNotFound`, `valueNotFound`)** → `references/unit-tests.md`
- **SwiftLint rule violation (`error: … (rule_id)`)** → `references/lint.md`
- **`superfluous_disable_command` on unchanged code** → `references/lint.md` (suspect version drift)
- **SwiftFormat would reformat a file (`--lint` non-zero)** → `references/lint.md`
- **markdownlint `MD0xx` violation** → `references/markdown.md`
## Output format
Produce exactly these three sections (keep it under ~150 words; if the caller
asked for a file, write the markdown there and nothing else, otherwise reply
directly):
**Summary:** which job and step failed, and the specific error (rule /
`file:line` / failing `Suite/test`).
**Cause:** the root cause, tied to a changed file where possible.
**Fix:** the concrete next step from the relevant reference file.
## Reference files
| File | Failing job | Covers |
|------|-------------|--------|
| `references/_index.md` | — | Navigation index by symptom |
| `references/lint.md` | Lint | SwiftLint `--strict`, SwiftFormat `--lint`, the six `Scripts/*.py` gates, pinned versions, drift |
| `references/markdown.md` | Lint Markdown | markdownlint on README, `CLAUDE.md`, DocC, `.claude/`, `knowledge/`, `.github/*.md` |
| `references/build.md` | Build and Test (build step); Build (\<platform\>) | compile errors, `--Werror` warnings, release build, simulator-matrix availability |
| `references/unit-tests.md` | Build and Test (test step); Test (\<timezone\>) | Swift Testing failures, JSON fixture/model mismatch, TZ-matrix date dependencies |
| `references/linux.md` | Build and Test (Linux) | Apple-only API gating, Foundation portability |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |