Fix Ci Train

Fix-CI Train

Walk a whole list of open pull requests and make their CI green — one pass, every PR. Read each PR's failing required checks, fetch the failing logs, consolidate a concrete per-PR CI-fix checklist, dispatch a team of parallel fixer sub-agents that apply the minimal fix and re-run the repo's quality gates, push to each PR branch, poll CI until every required check is SUCCESS, and report what's green, what broke out, and what still needs a human.

This is the fourth member of the train family and exists to unblock the CI gate that the rest of the family depends on:

• fix-ci-train — CI fix only (this skill): consumes failing required checks, applies minimal fixes, pushes, iterates until green. Never reads reviewer feedback. Never merges.
• review-train — review only: posts reviews + approved / changes-requested labels. Writes nothing to code.
• fix-train — fix only: consumes review change-requests, applies them, pushes. Never merges.
• merge-train — merge: orders, fixes CI/conflicts, merges.

The reason this skill exists separately from fix-train and merge-train: many review automations (including review-train when gated by a workflow) refuse to run until CI is green. Without a CI-only fixer, the pipeline deadlocks — review-train won't post, so fix-train has no review feedback to consume, so the queue stalls. fix-ci-train is the unlock step:

fix-ci-train  →  review-train  →  fix-train  →  re-review  →  merge-train
   (green CI)     (reviews)        (apply)      (approve)     (merge)

This skill performs irreversible shared-repo actions (committing, pushing to PR branches, commenting, optionally label edits). It follows the same grouped-confirmation model as its siblings: all collection and planning is read-only, one complete plan is presented, and it waits for a single explicit confirmation before any commit, push, or comment. Until the user confirms, nothing is written anywhere.

When to Activate

• User shares a GitHub pull-requests URL and asks to fix CI / make CI green / unblock the red PRs (not review, not address feedback, not merge).
• User says: "fix CI on every PR", "make the red builds green", "the review job is gated on CI — unblock the queue", "clear the ci-failing PRs", "drive CI to green across the open PRs".
• User invokes /fix-ci-train (optionally with a GitHub PRs URL or --dry-run).

If the user asks to address reviewer feedback, defer to fix-train. If they ask to review, defer to review-train. If they ask to merge / order / fix-then-merge, defer to merge-train. Do not blur the four.

A PR with green required checks is out of scope for this skill (nothing to fix). A PR with only non-required checks failing is reported but not fixed unless --include-non-required is set.

Inputs

• Primary: a GitHub pull-requests URL. Any of: /pulls, a search query (/pulls?q=...), a label/milestone filter, or a single PR URL. Honor the filter in the URL — only the PRs the URL would list are in scope. A single-PR URL ⇒ fix CI on just that one.
• If no URL is given, default to the current repo's open PRs (gh pr list); confirm the repo if ambiguous.
• Flags:
• --dry-run — produce the full plan + the per-PR CI-fix checklists and stop; never edit, commit, push, or comment.
• --include-non-required — also act on non-required check failures (default: only required checks count; non-required reds are listed in the plan but not fixed).
• --include-drafts — also fix CI on draft PRs (default: drafts are listed but skipped).
• --concurrency — max parallel fixer agents (default 4).
• --max-iterations — per-PR ceiling on consecutive fix→push→re-poll cycles before declaring a real defect (default: 4). Each iteration represents one fixer agent dispatch.
• --ci-timeout — per-PR ceiling on total wall-clock time spent waiting for CI on that PR (default: 45). Once hit, leave the PR as ci-still-pending and report; do not flip any label.
• --ci-poll — interval between gh pr checks polls (default: 30).
• --no-comment — apply + push the fixes but do not post the status comment.
• --no-label — do not touch labels (default: on green, remove ci-failing if present, add ci-green; on break-out, ensure ci-failing is present).
• --no-push — implement + verify locally and produce per-PR patches, but do not push or comment (stronger than --dry-run in that the work is actually done locally; useful for inspection).
• --scope — what kinds of fixes a sub-agent may apply. ci-only (default) = only changes that target a failing check (lint auto-fix, formatter, lockfile regen, type fix on the failing file, the specific failing test's setup/fixture, etc.). ci-and-deps = also allowed to bump a dependency or regenerate generated files when a failing check clearly points to it. Never allowed: feature changes, refactors, comment cleanup, anything orthogonal to the failing checks.

Preconditions

Verify before any analysis. If any fail, stop and report the blocker.

1. gh auth status succeeds and has repo + actions:read scope (needed to fetch run logs, push, and comment).
2. git is available and the working tree is clean (git status --porcelain empty). Fixer agents run in isolated worktrees, but a dirty primary tree still risks contamination — stop and ask the user to commit or stash.
3. The target repo is reachable via gh repo view /.
4. Resolve the default/integration branch: gh repo view --json defaultBranchRef -q .defaultBranchRef.name (never pushed to by this skill — recorded so fixers never target it).
5. Resolve the repo's required checks (so non-required failures are correctly downgraded): gh api repos///branches//protection --jq '.required_status_checks.contexts' if branch protection is in place. If the API returns 404 (no protection rules), fall back to: required = all checks that appear in statusCheckRollup for the PR. Record the set per PR.

Workflow

Phase 1 — Enumerate (read-only)

gh pr list --repo / --state open --limit 200 \
  --json number,title,headRefName,baseRefName,isDraft,author,url,labels,statusCheckRollup

Apply the URL's filter. Drafts are listed but skipped unless --include-drafts. A PR whose every required check is SUCCESS (or pending with no failures) is out of scope and reported as skipped — there is nothing to fix.

In-scope = at least one required check in FAILURE / CANCELLED / TIMED_OUT / ACTION_REQUIRED. With --include-non-required, also include PRs whose only failures are non-required checks (still reported separately).

Phase 2 — Collect failing checks per PR (read-only)

For each in-scope PR, gather every failing check, in parallel where possible:

• Rollup: gh pr view --repo / --json statusCheckRollup,headRefOid,headRefName — the canonical list of checks and their current state on the PR head commit. Capture name, status, conclusion, detailsUrl, and the databaseId / id needed to fetch logs.
• Required vs non-required: cross-reference with the required-checks set from preconditions. Non-required failures are listed but only fixed when --include-non-required is set.
• Failing logs: for each failing required (or in-scope non-required) check, fetch the failing-step log only:

``bash gh run view --repo / --log-failed ``

Truncate sensibly (keep the failing assertion / compiler error / stack trace; drop verbose setup noise) to keep the fixer prompt focused. If a check has no associated run-id (e.g. external status from a third-party service), capture detailsUrl and the status payload; report it but do not auto-fix — those almost always need human or external action.

• Head commit & diff for grounding: gh pr diff --repo / and gh pr view --json headRefOid — so each failing check can be tied to the PR's actual current code (not stale logs from a previous push).

• **Prior ` comment**: list issue comments authored by the current gh user that start with the ` marker — needed in Phase 6 to update instead of stack.

Phase 3 — Consolidate the per-PR CI-fix checklist (read-only)

For each PR, turn the collected failing checks into a deduplicated, concrete checklist. Each item: a stable id, the check name + run URL, the failure category (see below), a short defect summary (one or two lines extracted from the failing log), and the intended minimal fix (the obvious in-scope change — or needs-decision if not obvious).

Classify each item by category and actionability:

Failure categories (rough heuristics — adjust to what the log actually says):

• lint — ESLint / Ruff / Pylint / Clippy / RuboCop / etc. Almost always mechanical; many runners support --fix.
• format — Prettier / Black / Rustfmt / gofmt. Mechanical; the formatter's output IS the fix.
• types — tsc --noEmit / mypy / pyright / Flow / Go vet. Usually scoped, often mechanical when the message is precise.
• tests — unit / integration / e2e. Mechanical if the test is a snapshot/fixture mismatch or a clearly missed edge of the PR's own change. Real defect if the test is asserting business behavior the PR broke.
• build — Webpack / Vite / Next / Cargo / tsc emit. Often mechanical (missing import, wrong path, stale lockfile, peer dep mismatch).
• lockfile — pnpm/npm/yarn/cargo lockfile drift. Mechanical: regenerate.
• codegen — generated file out of sync (Prisma client, protobufs, GraphQL types, Prismic codegen, etc.). Mechanical: re-run the generator.
• infra — CI runner setup, env-var-missing, action-version-pinned-to-deleted-tag, network flake. Out of scope for this skill unless the fix is a workflow-file edit clearly on the PR's intent.
• flake — known-flaky check (intermittent, no log content from the actual SUT). Retry once via a no-op commit only if the repo has a documented retry pattern; otherwise surface as needs-decision.
• external — third-party status (preview deploy, security scanner, etc.) with no actionable log. Surface, do not auto-fix.
• unknown — can't categorize from the log. Surface as needs-decision.

Actionability:

• actionable — a concrete, unambiguous code change scoped to the failing check (and to the PR's own diff where possible). Examples: run the formatter, run the linter with --fix, fix the specific type error the compiler named, regenerate the lockfile, regenerate codegen, update a snapshot that legitimately moved with the PR's change, fix the obvious test-setup issue the log points at.
• needs-decision — ambiguous, contradicts the PR's intent, requires architectural choice, or would require touching code outside the PR's diff in a non-trivial way. Do not guess these. Surface them; never silently implement, never silently drop.
• out-of-scope — infra / external / non-required (unless --include-non-required). Reported, not acted on.

A PR with zero actionable items (all needs-decision / out-of-scope) is reported but not branched — there is nothing safe to auto-fix.

Phase 4 — Present the consolidated plan (the single confirmation gate)

Output one Markdown report (see Output Format). For every in-scope PR show: author, the failing-check names, the actionable / needs-decision / out-of-scope counts, the failure categories, the quality gates that will run locally before pushing, whether the status comment will be new or an update of a prior ` comment, and the planned label transition (ci-failing → ci-green` on success, kept on break-out).

Then ask one grouped confirmation:

> "Fix-CI plan ready: N PRs with M actionable failing checks total, D need a human decision, O are out-of-scope. I will, per PR in an isolated worktree: implement the minimal fix for each actionable check, run ` locally, commit, push to the PR branch, then poll gh pr checks until every required check is SUCCESS (bounded by --max-iterations and --ci-timeout) — re-dispatching the fixer agent with new failing logs each cycle. On green: post a status comment and flip the label (ci-failing → ci-green). On break-out: comment honestly, keep ci-failing`. No reviewer-feedback work, no merge, no orthogonal changes. Proceed with the full batch? (yes / dry-run / pick a subset)"

• --dry-run (or a dry-run answer) ⇒ stop here; write nothing.
• The user may approve a subset of PRs and/or deselect specific items; respect it exactly.
• Without an explicit "yes", do nothing.

Phase 5 — Dispatch the fixer team (writes; only after confirmation)

Spawn one fixer sub-agent per PR via the Agent tool with isolation: "worktree" so each agent works on an isolated copy of the repo and parallel fixes never collide. Batch at --concurrency (default 4) — send each batch as parallel tool calls in one message, wait, then the next batch.

Each sub-agent prompt is self-contained and must include:

• The PR number, title, author, head/base branch, URL, and head commit SHA.
• The full actionable CI-fix checklist for that PR (ids, check name, failure category, defect summary from the log, intended minimal fix). Explicitly exclude needs-decision / out-of-scope items.
• The relevant excerpts from the failing-check logs (truncated to the failing-step output).
• The PR diff for grounding.
• The detected quality-gate commands (lint / typecheck / test / build / codegen / lockfile) and the project's package manager / toolchain (honor CLAUDE.md if it mandates one — e.g. pnpm only, no npm).
• This instruction: "Check out the PR head branch (head SHA ) in your isolated worktree. For each listed actionable item, apply the minimal change that makes the named failing check pass — formatter output, linter --fix, the specific type/test fix the log points at, lockfile/codegen regeneration, etc. Touch only what the failing check requires; do not refactor, do not address comments, do not change behavior orthogonal to the failure. After each fix, re-run that check's local equivalent (e.g. pnpm lint, pnpm typecheck, pnpm test -- , the build) and confirm it passes locally before moving on. Then run the full local quality-gate suite to make sure you didn't break a sibling check. Commit with a clear message referencing the items addressed (e.g. ci(fix): address PR # CI items ci-1,ci-3). Output: per-item status (done / could-not-do + why), the list of files changed, the commit SHA, and the local gate results."
• The scope guardrail per --scope: "Scope = `. ci-only: only changes that target a failing check; no dependency bumps; no generated-file regeneration unless the failing check IS a codegen / lockfile` category. ci-and-deps: additionally allowed to bump a dependency or regenerate generated files when a failing check clearly points to it. Never allowed in either: feature changes, refactors of code unrelated to the failure, unsolicited comment/lint cleanup of orthogonal files."
• This guardrail: "CI fix only. Do not merge, do not close, do not rebase onto or push the integration branch, do not address reviewer comments (that's fix-train's job), do not resolve unrelated CI failures originating outside the PR's own diff (an unrelated flaky integration test that pre-dates this PR, a broken main, an infrastructure outage — surface, do not fix). Push only the PR head branch."

Use subagent_type: general-purpose (this is implementation, not review). Collect each agent's per-item status, files changed, commit SHA, and local-gate results.

Trust but verify. A fixer agent's summary states intent, not ground truth. Before treating a PR as fixed, verify against the actually-pushed diff: the changed files plausibly match the named failing checks, no out-of-scope files were touched (especially: no app/feature code when the only failures were lint / format; no production source when only tests failed in a way the agent c

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: big-emotion
• Source: big-emotion/agent-atelier
• License: MIT

Install and usage instructions live in the source repository linked above.