fix-integration-failures

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.

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:

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:

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