adamayoung/TMDb / .claude/skills/fix-integration-failures
fix-integration-failures
VerifiedDiagnose and fix a failing scheduled (or standalone) TMDb Integration workflow run — re-run transients, or fix real drift on a branch off main, then PR and (optionally) merge. Use for the weekly Sunday Integration cron failure, or any red Integration run not tied to an open PR.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
SKILL.md
View on GitHub---
name: fix-integration-failures
description: Diagnose and fix a failing scheduled (or standalone) TMDb Integration workflow run — re-run transients, or fix real drift on a branch off main, then PR and (optionally) merge. Use for the weekly Sunday Integration cron failure, or any red Integration run not tied to an open PR.
---
# Fix Integration workflow failures
The **`Integration`** workflow (`.github/workflows/integration.yml`) runs the
live-API integration suite on a **weekly schedule** (`cron: '0 0 * * 0'` — Sunday
00:00 UTC), as well as on PRs/pushes. The scheduled run is a **live-API canary**:
nothing in the code changed, so a failure means the live TMDb API drifted, a test's
assumed data went stale, or a transient error/rate-limit hit. This skill takes such
a failure from **red run → green main**: diagnose it, then either re-run a transient
or fix the real cause on its own branch and open (and optionally merge) a PR.
> **Scope.** This is for an Integration failure **not attached to an open feature
> PR** — the scheduled canary, a `workflow_dispatch`, or a failure on `main`. When a
> failing Integration check belongs to an **open PR**, `/watch-pr` and
> `/fix-pr-checks` own that; they delegate the *pre-existing/unrelated* case back
> here (fix on a branch off `main`), which is exactly this skill's job.
**Mode** — check the arguments passed to this skill (shown at the end). If they
include `merge` (e.g. `/fix-integration-failures merge`), **auto-merge** the fix PR
once green. Otherwise stop at **ready-to-merge** and hand off (default).
## Agent behaviour contract
1. **Never edit `main` directly** (`CLAUDE.md`). Any fix lands on a `fix/<slug>`
branch off `main`, via a PR.
2. **Diagnose before fixing.** Always run `/diagnose-integration-failure` first;
let its ranked cause drive the fix. Don't guess.
**Check the diagnosis carries its evidence.** A shape-change (cause 1) or
drifted-data (cause 2) conclusion must arrive with an `observed:` line — the
live call that saw today's response. Missing one, **re-run the diagnosis
once** asking for it. Still missing → treat that cause as **unverified**:
proceed, but say so in the PR body and in `claude-analysis.md`, and never
describe it as confirmed drift. **Re-run once, not in a loop** — a headless
run has no MCP and legitimately cannot observe (it reports
`observed: unavailable (headless)`), so an unbounded retry would spin
forever. Transient (cause 3) and in-diff regression (cause 0) carry no
`observed:` line by design; do not demand one.
3. **Distinguish transient from real.** A re-run is the cheap test. Only open a PR
for a cause that survives a re-run (or is clearly a data/shape drift).
4. **Test-first for real fixes.** A model/decoder fix follows `canon-tdd` (failing
unit test + fixture, then the fix). A drifted-assertion fix updates the
integration test to assert **behaviour, not a brittle exact value**.
5. **The gate is `make ci`.** Never open the PR until it passes locally.
6. **Don't paper over a real regression.** If the cause is a genuine library bug
(not drift/transient), fix it properly or stop and report — never just relax a
test to hide it.
## 0. Find the failing run
> **Interactive vs headless.** The steps below use the **GitHub MCP**
> (`mcp__github__*`, owner/repo from the `origin` remote). When this skill runs
> **headless** from `integration-failure.yml` — a CI runner, where the user-scoped
> MCP is **not** mounted — use the `gh` equivalents instead (given inline at each
> step and in *Running headless* below); that path stays 100% `gh`/`git`.
Find the failing run with `mcp__github__actions_list` method `list_workflow_runs`
(owner/repo from `origin`, `resource_id: integration.yml`,
`workflow_runs_filter: { event: schedule, status: completed }`). The `status` enum has
no `failure` value, so filter the results to `conclusion == "failure"` yourself.
- Prefer the most recent **`schedule`** (or `workflow_dispatch`) run on `main`.
- Note its run `id` and `event` (sets the cause ranking).
- No failing run → report "Integration is green, nothing to fix" and stop.
- **Headless:** `gh run list --workflow Integration --status failure --limit 5 --json databaseId,event,headBranch,conclusion,createdAt,displayTitle`.
## 1. Diagnose
Invoke **`/diagnose-integration-failure`**, handing it the run id (it fetches the
failed-job logs — via `mcp__github__get_job_logs`, or `gh run view --log-failed` when
headless). It returns the three-section analysis — Summary,
Likely cause (ranked; for a scheduled run it leads with backend/data drift, **not**
a code regression), and Suggested fix. Use that ranking to choose the path below.
## 2. Transient? Re-run first
If the diagnosis points to **case 3** (HTTP 429 / rate-limit, a timeout near the
30-min cap, or a truncated log with no assertion failure):
Re-run the failed jobs with `mcp__github__actions_run_trigger` method
`rerun_failed_jobs` (owner/repo from `origin`, `run_id: <id>`), then block on the
re-run with `gh run watch <run-id>` (the MCP has no blocking-wait equivalent). After
it returns, re-read the conclusion with `mcp__github__actions_get` method
`get_workflow_run` (`resource_id: <id>`) — don't trust the rerun call to surface it.
```bash
gh run watch <run-id> # blocking wait — kept on gh
```
- **Green on re-run** → it was transient. Report and stop; no PR needed.
- **Fails the same way again** → treat as deterministic; go to §3.
- **Headless:** `gh run rerun <run-id> --failed` then `gh run watch <run-id>`.
(The integration client already retries 429/5xx with backoff, so a true transient
that survives a re-run is uncommon — a repeat failure is usually real drift.)
## 3. Fix the real cause on a branch off `main`
Reproduce locally first to confirm and to get a fast edit loop. Branch **off
`origin/main` directly — never `git checkout main` first**. This is
**worktree-safe**: when this skill is invoked from a `/deliver` worktree (via
`/watch-pr` §1c), `main` is usually checked out in the main working copy, so
`git checkout main` fails with `fatal: 'main' is already used by worktree …` —
the same trap `/pr` documents for its rebase step:
```bash
git fetch origin
git checkout -b fix/<slug> origin/main # e.g. fix/<service>-integration-drift
```
**Invoked mid-`/deliver` (from `/watch-pr`)?** Don't create the fix branch in
the deliverable's worktree — that switches its checkout away from the feature
branch being watched. Give the fix its own worktree instead and work there,
removing it once the fix PR merges:
```bash
git worktree add .claude/worktrees/fix-<slug> -b fix/<slug> origin/main
```
Run the failing suite locally to reproduce — `/integration-test` (or
`swift test --filter <Suite>/<test>`). Then fix per the diagnosis:
- **TMDb backend / response-shape change** (a field added, removed, renamed, or now
nullable) → fix the Swift model / `CodingKeys` / fixture **test-first**
(`canon-tdd`): add a failing unit test + a JSON fixture matching the *current*
live shape. The diagnosis's `observed:` line tells you **which** endpoint
drifted and how, but it is a one-line summary (and `unavailable` headless) —
**not** a response body, so it cannot source a fixture. **Fetch the real
response with `mcp__tmdb__*`** and build the fixture from that, cross-checking
the OpenAPI spec for the documented shape — then the model fix.
- **Stale assumed data** (a test asserts a specific live title, count, id, date, or
ordering that drifted) → relax the integration assertion to verify **behaviour,
not a brittle exact value** (e.g. assert non-empty / a stable property / `>= 1`
rather than an exact count). Match the robust pattern already used by sibling
tests in the same suite.
- **A genuine library regression** → fix it properly, test-first. If it is not a
quick, confident fix, **stop and report** — don't merge a workaround.
Verify: `/integration-test` green for the touched suite, then **`make ci`**
(mandatory full gate). If `make ci` is red, fix and re-run — never PR on red.
## 4. Open the PR (and optionally merge)
Run **`/pr`** to commit (gitmoji), push, and open the PR (`🐛`/`✅`/`♻️` as fits;
`make ci` runs again inside `/pr`). Then run **`/watch-pr`** to drive it to ready:
- **Default (no `merge`)** → `/watch-pr` watch-only: report the ready PR URL and
**stop** for the user to merge.
- **`merge`** → `/watch-pr merge`: squash-merge once green, then report.
`/watch-pr` handles any further transient flakes on the PR's own checks (re-run),
so a live-API hiccup during CI won't strand the fix.
## 5. Report
Close with: the run id that failed, the diagnosis verdict (transient vs real), what
you changed (file + one line) or that a re-run cleared it, the PR URL and whether it
merged, and anything left for the user (e.g. a real regression you chose not to
auto-fix).
## Running headless (from `integration-failure.yml`)
When the **Integration Failure Alert** workflow invokes this skill on a scheduled
failure, it runs non-interactively, so adapt:
- A failing-step log is already at **`failure-log.txt`** in the workspace — diagnose
from it (pass it to `/diagnose-integration-failure`); don't re-download logs.
- **Verify with the targeted suite + a build** — `swift build --build-tests` and
`swift test --filter <Suite>/<test>` — **not** the full `make ci`. The **opened
PR's own CI** (`ci.yml` + `integration.yml`) is the authoritative gate; the alert
job need not replicate the whole pinned-lint/xcsift toolchain.
- **Open the PR with `git`/`gh` directly** (`git checkout -b` → commit → push →
`gh pr create`), **not** `/pr` — `/pr` runs the full `make ci`, which the
lightweight alert job can't satisfy. The format/lint hooks still reshape files on
edit, so the diff stays clean.
- **Then STOP** — do **not** run `/watch-pr` and do **not** merge (a human reviews
it). Write the diagnosis to `claude-analysis.md` and, if you open a PR, its URL on
one line to `pr-url.txt`.
- If the cause is **transient** (re-run territory) or a **genuine regression you
should not auto-fix**, open **no** PR — explain in `claude-analysis.md` so the
alert issue carries it.
## Guardrails
- Never edit `.github/workflows/*` to force a check green, and never force-push,
without surfacing to the user first.
- One failing run can surface several drifted assertions — fix them together in one
PR, but keep each change minimal and behaviour-preserving.
- If the live API is broadly down/throttled (many unrelated suites failing fast),
that's an outage, not a fix target — report and wait it out.
- Capture anything durable you learned (a new live-API shape, a recurring drift)
with `/capture-knowledge` before the PR, so the fixture/notes land with it.
Arguments: $ARGUMENTS
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |