fix-pr-ci-checks

Fix PR CI Checks

Fetch the failing CI checks on a PR — GitHub Actions workflows and any check surfaced by gh pr checks — triage each failure with the user, diagnose the cause (delegating test failures to test:triage-tests), apply fixes, run the matching local linters and tests, commit (amend or follow-up depending on review state), and push to re-trigger CI. Then hand off to release:read-ci-status --watch to confirm the build goes green.

Works for any repo via the gh CLI; derive owner/repo from gh repo view rather than hardcoding.

Scope: failing CI checks, not review comments. If the user wants to address reviewer/bugbot comments, that's the sibling skill fix-pr-feedback. This skill is single-pass and human-in-the-loop: it does not loop, and it does not watch CI to green itself (that's release:read-ci-status's job).

Composition / dependencies:

• Composes release:read-ci-status to fetch CI state. Read-only.
• Composes test:triage-tests (test plugin) to diagnose test failures — it auto-routes E2E/crash/rspec/jest and diagnoses and recommends; it does not fix.
• Sibling of fix-pr-feedback (engineering plugin), which addresses review comments. A future orchestrator / ship-practice loops the two to drive a PR both green and feedback-addressed.

Step 1: Identify the PR

• If $ARGUMENTS is provided, use it. Accept either a PR number or a full URL (https://github.com/{owner}/{repo}/pull/{number} — extract owner/repo/number from the URL).
• Otherwise auto-detect: a. Try gh pr view --json number --jq .number (works when checked out on the PR's branch). b. If that fails, search by branch name: gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'.
• If neither works, ask the user for the PR number.
• Derive {owner}/{repo} from gh repo view --json nameWithOwner --jq .nameWithOwner (or from the URL).
• Store the PR number and owner/repo for all subsequent steps.

Step 2: Verify the correct, current branch

• Get the PR's branch: gh pr view <N> --json headRefName --jq .headRefName
• Compare with git branch --show-current.
• If they differ, warn the user and offer to git checkout <pr-branch> && git pull --ff-only. Do not proceed until on the PR branch — the failing checks were produced against the PR branch's content, and fixes only make sense there.
• Check the branch is current, and rebase if it's behind. Determine the base branch (BASE=$(gh pr view <N> --json baseRefName --jq .baseRefName), usually main), then git fetch origin "$BASE" && git log --oneline HEAD..origin/$BASE. If that shows any commits, the branch is behind — rebase it: git rebase origin/$BASE, resolving conflicts before applying fixes. This repo requires branches be up-to-date with main to merge, so the rebase has to happen eventually anyway — do it now, and a failing check is sometimes nothing more than a stale base. If the rebase does not complete cleanly (conflicts, or a nonzero exit leaving the repo mid-rebase), stop and surface it to the user — never edit, commit, or push while mid-rebase. Confirm the rebase finished (git status shows no rebase in progress) before continuing. Do not talk yourself out of it because the failing check looks unrelated: a behind branch can still conflict on shared files (plugin manifests, version bumps, lockfiles, changelogs), and those conflicts surface only on rebase. Do the rebase before the Step 3 fetch; if you rebase after already fetching CI state, re-run the entire Step 3 fetch — a rebase produces new commits and a new CI run, so the prior failing checks/logs are stale. (A rebase rewrites history → the later push needs --force-with-lease. Note: rebasing + force-pushing an approved PR usually dismisses its approvals — re-check reviewDecision in Step 7 afterward, since the PR may no longer be approved.)

Step 3: Fetch failing checks

Prefer composing release:read-ci-status (via the Skill tool) on the PR number to get the current check states — it wraps gh pr checks / gh run view read-only and returns a per-check status table. Otherwise fetch inline:

• List every check and its conclusion:

  gh pr checks <N> --repo <owner>/<repo>
  

• For each failing GitHub Actions check, pull the failing job logs from its run:

  gh run view <run-id> --repo <owner>/<repo> --json status,conclusion,jobs,url
  gh run view <run-id> --repo <owner>/<repo> --log-failed
  

  (--log-failed prints only the failed steps' logs — far less noise than the full log.)
• Collect, per failing check: check name → conclusion → failing job → relevant log excerpt (the assertion, compiler/linter error, or stack frame — not the whole log).
• Stop only when there are no failing checks. If everything is passing or in-progress, report the current state (defer to release:read-ci-status for a live snapshot) and stop — there is nothing to fix.

Step 4: Classify each failing check

Sort every failing check into one of three buckets:

• (a) Fixable code failure — a lint/format/typecheck/build/unit/integration/e2e failure caused by the code on the branch. → goes into the fix queue.
• (b) Human-gate / not-a-code-failure — waiting-on-review, required-reviewers, merge-queue, draft-blocked, or similar process gates. → SKIP. Never try to "fix" these with code; they clear when a human or the queue acts.
• (c) Flaky / infra / timeout / external — runner died, network blip, third-party outage, a known-flaky test. → surface to the user; do not blindly re-run or thrash. Guessing-and-retrying is the opposite of systematic debugging — name the suspected cause and let the user decide (re-run, wait, or escalate). This skill never re-runs CI on its own.

Present a triage table:

| # | Check | Failure type | Diagnosis | Proposed action |

Failure type is code / human-gate / flaky-or-infra. Proposed action is fix / skip / surface (your call).

AI-reviewer checks (e.g. Cursor Bugbot, Copilot) lie quiet, not clean. A skipping/NEUTRAL state on an AI code-review bot reflects whether its run was gated/neutralized — not whether it found anything. Bugbot routinely reads skipping in gh pr checks while having fully run and posted high-severity review comments. So never read a neutral/green board as "no findings." Those findings are review comments, not checks — out of scope here. Surface to the user that Bugbot may have left comments and point them at the sibling fix-pr-feedback skill; do not try to address them in this skill.

Step 5: Triage with the user

Present numbered options (use AskUserQuestion) for how to handle each open failure:

1. Explain — walk through the failing check's log excerpt and the likely cause; no changes.
2. Fix — diagnose and apply a code fix (Step 6), then verify locally.
3. Skip — leave this check alone (always the action for human-gate checks; the default for flaky/infra unless the user wants to investigate).

The user may scope by number (e.g. "fix #1 and #3, explain #2, skip #4"). Collect decisions into a fix queue.

• For test-type failures (rspec/jest/unit/integration/e2e/crash), delegate diagnosis to the test:triage-tests skill (via the Skill tool) — forward the failing report/CI link/spec output verbatim so it can root-cause and classify (code bug vs. test bug vs. flaky vs. environment) before you propose a fix. Do not jump straight to editing code for a test failure; let triage classify first.
• For lint / format / typecheck / build failures, diagnose directly from the log excerpt — these are usually self-evident (offense + file:line).

Step 6: Apply fixes

For each item in the fix queue:

a. Read the relevant file and lines. b. Diagnose and apply the fix. (For test failures, use the root cause from triage-tests.) c. Identify which commit in the PR introduced the affected lines (reuse $BASE from Step 2):

• git log "origin/$BASE..HEAD" --follow --format="%H %s" -- <file> to find candidate commits.
• git log "origin/$BASE..HEAD" --oneline for context if needed. d. Track which files were modified and which commits they belong to.

After all fixes are applied, run local verification before pushing — match the linter/tests to the file types and the failing check:

• Ruby (.rb): rubocop <files>
• JS / TS (.js, .jsx, .ts, .tsx): the project's lint command (e.g. npx eslint <files>); the relevant tests (e.g. npx jest <path>) if a test check failed.
• Markdown (.md): npx prettier --check <files>
• Other languages: use the repo's configured linter/formatter and test runner; prefer whatever the project already standardizes on.
• Fix any lint/test errors that arise, iterating until clean.

For a test fix specifically, re-run the exact failing spec/test locally and confirm it now passes before trusting CI — see the failure go green on your machine first (verify-before-completion: don't push a "fix" you haven't watched pass). If you can't reproduce the failure locally, say so in the triage rather than assuming the fix worked.

Step 7: Commit and push

• Choose a commit strategy from the PR's review state (gh pr view <N> --json reviewDecision):
  • Not yet approved: amend into the originating commit(s) (from Step 6) to keep history clean.
    • All fixes belong to the current HEAD commit: git add <files> && git commit --amend --no-edit.
    • Fixes belong to an earlier commit, or span several commits: --amend only touches HEAD, so do not use it here — it would fold every staged fix into HEAD and misplace them. Instead, stage and create a fixup per originating commit (git add <files-for-that-commit> && git commit --fixup=<sha>), then fold them in with git rebase --autosquash origin/$BASE (a rewrite → push needs --force-with-lease). Commit each commit's fixes separately so each fixup targets the right <sha>.
  • Already approved: prefer a separate follow-up commit (git add <files> && git commit -m "...") so re-reviewers see exactly what changed since approval, instead of rewriting approved history.
• GATE: Re-run linters on all changed files after committing. Do NOT push until all linters pass cleanly. If a new offense was introduced by the fix, resolve it (refactor, or a targeted disable comment) and re-commit before proceeding.
• GATE: Present a summary of all changes (fixes applied, checks addressed) and ask the user to confirm before pushing. Do NOT push until the user approves.
• Push: plain git push for a new follow-up commit; git push --force-with-lease if you amended or rebased. Pushing re-triggers CI.
• GATE: Verify the push actually landed before claiming a fix shipped. Check the push exit status; if it was rejected (e.g. a stale --force-with-lease lease, or non-fast-forward), stop and surface it — do not proceed to Step 8 and tell the user CI was re-triggered for a commit that never reached the remote. Confirm git rev-parse HEAD matches the remote (git rev-parse @{u}, or re-check the PR head) before continuing.

Step 8: Hand off to verify

There are no comment replies to post. Instead:

• Tell the user the pushed fix has re-triggered CI, and to confirm the build with release:read-ci-status <N> --watch (reference the skill by name). Do not watch CI to green yourself — that preserves this skill's single-pass contract and is release:read-ci-status's job.
• If any checks were SKIPPED as human-gate or flaky/infra in Step 4, restate them so the user knows exactly what's still red and why (e.g. "required-reviewers is still red — that clears when a reviewer approves; flaky-integration-test re-ran clean is your call").
• If an AI-reviewer check (e.g. Cursor Bugbot) showed skipping/NEUTRAL, remind the user that does not mean it had no findings — it may have posted review comments that this skill doesn't touch. Point them at fix-pr-feedback to address those.

Output

Summary table:

| # | Check | Failure type | Action | Commit |

Followed by the PR URL and the line: "Run release:read-ci-status <N> --watch to confirm CI goes green."

Rules

• Never push without explicit user confirmation. Always present the planned fixes and wait for approval.
• Gate every linter pass before pushing, and re-run them after committing; iterate until clean.
• Verify the push landed before telling the user CI was re-triggered.
• Never propose code fixes for a human-gate check (waiting-on-review, merge-queue, draft-blocked) — they aren't code failures.
• Don't blind-retry flaky/infra checks. Surface the suspected cause and let the user decide; this skill never re-runs CI itself.
• This skill does one pass. It doesn't loop and doesn't watch CI to green. To iterate, re-invoke it (or use the future orchestrator that pairs it with fix-pr-feedback).