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 |
references/linux.md
View on GitHub# Linux build/test failure (Build and Test (Linux))
The **Build and Test (Linux)** job runs in the `swift:6.1-jammy` container:
```bash
swift build --build-tests -Xswiftc -warnings-as-errors
swift test --skip-build --filter "TMDbTests|TMDbTestingTests|TMDbIntelligenceTests|TMDbIntelligenceTestingTests"
swift build -c release -Xswiftc -warnings-as-errors
```
The telltale signature: **it fails on Linux but the macOS `Build and Test` job
passes.** That is almost always a **platform-portability** problem, not a logic
bug — the package targets Linux alongside the Apple platforms.
## Reading the failure
- `error: '<API>' is unavailable` / `cannot find '<symbol>' in scope` that only
appears in the Linux job → an Apple-only API reached Linux compilation.
- A test failure present only on Linux → behaviour that differs across Foundation
implementations (date formatting, URL handling, locale, etc.).
## Common causes & fixes
1. **Apple-only framework used without gating.** This package deliberately gates
Apple-only services:
- `naturalLanguageSearch` is behind `#if canImport(NaturalLanguage)`.
- `TMDbToolbox` / `LanguageModelTools` are behind
`#if canImport(FoundationModels) && !os(tvOS)` with
`@available(iOS 26, macOS 26, …)`.
If new code calls `NaturalLanguage`, `FoundationModels`, `CoreML`, etc.
without the same `#if canImport(...)` guard (and an `@available` where
needed), Linux can't compile it.
- Fix: wrap the Apple-only code path in `#if canImport(<Framework>)` and
provide a Linux fallback (or exclude the feature on Linux, matching how
`naturalLanguageSearch` degrades).
2. **Foundation API differences.** Some Foundation APIs behave differently or are
missing on swift-corelibs-foundation. Recent work in this repo moved off
`DateFormatter` to `Date.ParseStrategy` / `Date.ISO8601FormatStyle` partly for
cross-platform consistency — keep to those portable APIs.
- Fix: use the portable API; if a value differs, assert on the parsed value
(`try #require(...)`) rather than a locale-dependent string.
3. **`#if os(...)` / availability mismatch** — code compiled into the Linux
target that references symbols only present on Apple platforms.
## Reproduce locally
Run the Linux toolchain in Docker (matches CI):
```bash
make build-linux # swift build in a Swift Docker container
make test-linux # swift test in a Swift Docker container
```
These surface failures the macOS build never will.
## Output
**Summary:** Build and Test (Linux) — `error` at `file:line`, Linux-only.
**Cause:** Apple-only API/Foundation difference reaching the Linux target.
**Fix:** gate behind `#if canImport(...)` / use a portable API; verify with
`make build-linux` / `make test-linux`.
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 |