Skip to content

adamayoung/TMDb / .claude/skills/fix-integration-failures

fix-integration-failures

Verified

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.

FileKindSize
SKILL.mdskill md10.7 KB
---
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
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall