CI Fix

CI fix

Repair, classify, or sweep failing CI on a PR or branch. Three modes: fix (default; interactive or autonomous), classify (read-only diagnosis), and sweep (bounded background monitor). Never widen workflow permissions, never add pull_request_target, never offer a rerun in place of a code fix. Merge conflicts route to resolve-merge-conflicts; non-CI bugs route to strike-the-root.

Contract

Inputs

• mode: fix (default), classify, or sweep.
• repo: path inside the repo (default .). Must be a Git repository.
• Target: PR number or URL, original branch name, or run ID; defaults to the current branch's PR. A working tree already carrying the in-progress fix is fine.
• gh authenticated for the repo host with workflow/repo scopes. Classify stands alone without gh; in fix and sweep an unauthenticated CLI stops the skill before any change.
• Optional: a specific job ID for full-log inspection, or an artifact download when logs alone do not identify the cause.
• Classify: the check name, its status (failed, absent, pending, unstable, or unexpected), and the run identifier or URL that produced the report; optional: the failing job log, the changed files or commit range under test, and any prior classification of the same check.
• Sweep: the base commit the CI run used, the verifier command that independently confirms a repair, and the attempt cap; optional: a flake-detection window and a circuit-breaker threshold.

Procedure

1. Select the mode: classify when the user asks for a diagnosis or plan without a patch, sweep when a bounded monitor over an attempt window is requested, fix otherwise. Done when: the mode is stated and its inputs above are present, or the missing input is reported.
2. Set GH_PAGER=cat on every gh invocation; the CLI has no global --no-pager option and blocks on a pager in non-interactive contexts without it. Verify authentication with gh auth status. In fix and sweep, stop and ask the user to run gh auth login when unauthenticated; no mutation before this. In classify, continue without gh; the classification stands alone. Done when: an authenticated identity is confirmed by gh auth status output, the handoff is asked and no mutation has occurred, or classify proceeds without gh and says so.
3. Record the failing identity. Classify: record the check name, status, and run identifier before reading anything else; an absent check or a check that never ran is a distinct input, not a missing one. Fix and sweep: resolve the failing run; PR: gh pr view --json number,url; non-PR branch or supplied run ID: gh run list --branch <branch> --status failure --limit 5, then gh run view <run-id>. Done when: classify has the check name, status, and run identifier recorded, or fix and sweep have one failing run identified by its run ID and branch name from command output.
4. Gather failure evidence (GitHub Actions only). Prefer the bundled script, which handles gh field drift, run-id/job-id extraction, failure-snippet extraction, and exits non-zero while failures remain:
   • python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>" (--json for machine output).
   • Manual fallback: GH_PAGER=cat gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow; rerun with the fields gh accepts if one is rejected. Extract the run id from detailsUrl, then GH_PAGER=cat gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha, GH_PAGER=cat gh run view <run_id> --log-failed for the failed jobs only or --log for all, GH_PAGER=cat gh run view <run-id> --log --job <job-id> for one failing job; for evidence logs cannot supply, gh run download <run-id> -D .artifacts/<run-id>. If a run log is still in progress, fetch job logs via gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs".
   • A check whose detailsUrl is not a GitHub Actions run is external: report the URL only; do not attempt Buildkite or other providers. Done when: every failing check has a name, URL, and a log snippet from command output, or an explicit log_pending/log_unavailable marker; never a fabricated snippet. In classify, preserve the exact failure line, signal, or message.
5. Mode classify (read-only; stop before any write):
   1. Compare the failure against the commit range and changed files under test; decide whether the failing code path was touched by the change or predates it. Before flagging a test failure as a regression, check whether the same test previously passed in CI and note environment-specific or flaky cases rather than treating them as regressions. Done when: the failing path is determined as in-diff or pre-existing.
   2. Classify into exactly one class: regression (the change introduced or exposed the failure; the failing path is in the diff), flake/watch (timing-, order-, or environment-dependent; passes on retry or across runs without a code change), infrastructure (runner, network, quota, service outage, or resource exhaustion, not the code under test), configuration (build, config, dependency, or environment setup, not product logic), policy/absent-CI (absent, skipped, not configured, or blocked by a branch-protection or policy rule), or human escalation (evidence insufficient, contradictory, or outside the five classes; a human must decide). If a prior classification of the same check matches the new evidence, note the repeat; if it contradicts, re-classify from the new evidence. Done when: the failure is classified into exactly one class from observed evidence.
   3. Assign the next owner from the class: regression and configuration to the change author, flake/watch to the test or platform owner, infrastructure to the platform or runner owner, policy/absent-CI to the repository or CI-config owner, human escalation to a human reviewer. State the next action concretely in one sentence. Done when: the next owner is assigned from the class and the one-sentence next action is recorded.
   4. Emit a reviewable fix plan when a PR and authenticated gh are available: view the PR with GH_PAGER=cat gh pr view <branch> --json number,title,url,state and fetch the check rollup with --json statusCheckRollup; extract each failed check's logs with GH_PAGER=cat gh run view <run-id> --log-failed, collecting error messages with file paths and line numbers, compilation errors, lint names, test failure messages and stack traces, and build root causes. If any check is still in progress, report the partial state and stop; do not diagnose incomplete checks. Then write the plan: a problem statement summarizing the failing checks, the current state listing each error and its location, proposed changes grouped by category (formatting, linting, compilation, test failures, platform-specific), and validation steps (fmt, lint, tests, presubmit). Fix one category at a time. Apply no code change. Mark any unread run as untriaged. Done when: the plan carries the problem statement, current state, per-category proposed changes, and validation steps, or the plan is skipped and reported because no PR or gh is available. Then stop; if any further step would require a write, return human escalation.
6. Mode fix:
   1. Triage every failing check: classify each as a root cause or a downstream symptom of another failure. A single root cause may surface as several failing checks. Order the work so root causes are fixed before the symptoms they produce. Done when: every failing check is classified as root cause or symptom in a written list, and the work order places root causes before their symptoms.
   2. For each root-cause failure, read the failure log and the relevant source to determine the smallest deterministic fix for that cause; prefer a code change over workflow plumbing; for a flaky test, fix the nondeterminism instead of rerunning. Request approval before editing any file. Done when: the plan is approved in writing with the file paths and change described, or refused; then report the plan and wait without editing.
   3. Implement the approved plan and summarize diffs and tests. Keep the change set inside the failing job/step where possible. Done when: git diff --name-only lists only the approved file paths and the diff summary matches the approved plan.
   4. Run the local equivalent of each failing CI check to confirm the fix before any push. Done when: the local check command exits 0 with its output captured, confirming the fix reproduces green locally.
   5. Capture the current remote status with gh pr checks <pr>. Interactive mode has not pushed, so report local-fix-ready with the local proof and the observed red or pending remote checks; never imply that local edits changed CI. If the remote checks are already green because another actor updated the branch, report the observed green state without attributing it to the local patch. Done when: the current gh pr checks output is captured and the result is local-fix-ready with remote status quoted, or an independently updated remote run is observed green with its output quoted. Autonomous branch (explicit user ask only): enter only when the user asks for the fix to be pushed (for example "push the fix" or "land it on a fix branch"); never self-initiated. Before any mutation, preview the failing job, the exact change set, and the target branch ci-fix/<original-branch>; the plan approval from fix step 2 doubles as the push approval once the preview is acknowledged.
   6. If workflow files must change: keep existing permissions: minimal, never broaden token access, no pull_request_target unless the user explicitly requested it. Done when: git diff on workflow files touches no permission key outside the previewed set.
   7. Create or update the branch. New: git checkout -b ci-fix/<original-branch>. Existing: show its current commits, confirm reuse with the user, git checkout ci-fix/<original-branch>, then git pull origin <original-branch>. Done when: the branch is checked out and git log --oneline -1 shows it carries only the previewed change.
   8. Stage only the exact paths in the approved preview with git add -- <paths>, then inspect the staged path list and patch. Stop if the staged set contains any extra path. Commit fix: resolve CI failure in <job-name>, then push git push -u origin ci-fix/<original-branch> (plain git push once upstream is set). Done when: git diff --cached --name-only lists only the approved paths and git push succeeds with the remote branch at the pushed SHA confirmed by git rev-parse origin/ci-fix/<original-branch>.
   9. Watch: gh run list --branch ci-fix/<original-branch> --limit 1 for the new run id, then gh run watch <new-run-id> --exit-status. Re-trigger only failed jobs with gh run rerun <new-run-id> --failed when the evidence is infrastructure or a confirmed flake and the user approves; a rerun never substitutes for a deterministic fix. Done when: gh run view <new-run-id> --json conclusion reports success, or the failure and recovery section applies.
   10. If new failures appear, repeat from fix step 1 treating the new failures as the current set. Stop only when every check in the set is green. Done when: every check in the set is green, or a failure class in the failure and recovery section applies.
7. Mode sweep:
   1. On each tick, fetch the current set of failing CI checks for the target run and record the attempt number against the configured cap. If the attempt cap is reached, stop and hand off; do not start a new repair. Done when: the failing checks are fetched and the attempt number is recorded, or the sweep stops at the cap with a handoff.
   2. Pick one failing check and reproduce the failure locally in an isolated worktree created from the base commit the CI run used. Classify the failure: reproduce the root cause, or classify it non-actionable (flake, environment, upstream). If the failure is a flake or the cause is ambiguous, hand off and do not patch. Done when: the failure is reproduced locally or confirmed non-reproducible, and classified as root cause or non-actionable, or handed off.
   3. For a reproducible root cause, implement one minimal isolated repair in the worktree: the smallest change that fixes the reproduced cause and nothing else. Run the verifier in the worktree independently of the repair; confirm the failing check passes and no other check regresses. If the verifier fails or regresses, do not widen the patch; increment the attempt counter and either retry within budget or hand off. Done when: the minimal repair is implemented and the verifier confirms the fix with no regression, or the verifier failure is recorded and the retry-or-handoff decision is made.
   4. Return the verified patch as a proposal (diff or branch) with the reproduced root cause, the verifier evidence, and the attempt count. Do not push, merge, or publish; a worktree repair is never merged. If the circuit breaker trips (repeated non-convergence, repeated flakes, or budget exhaustion), stop the sweep and hand off with the accumulated evidence. Done when: the verified patch is returned as a proposal with evidence, or the sweep stops with a handoff and accumulated evidence.

Failure and recovery

• gh unauthenticated, or no failing run found for the supplied PR/branch/run ID: stop and report; nothing committed or pushed. In classify, skip the fix plan, report the missing prerequisite, and never attempt credential setup.
• Classify evidence insufficient or contradictory: do not guess a class. Return human escalation naming the missing evidence, or stating both signals when they imply different classes; never average or pick arbitrarily.
• Classify no-CI state: a check that is absent or never ran is policy/absent-CI; surface it, never treat it as passing or skip it. A check pending past the expected window or blocked by policy is surfaced with its next owner, never marked done. No PR for the branch: classification stands alone, skip the fix plan, and report that no PR exists; do not create one.
• Classify partial evidence: classify each inspectable check and explicitly mark the rest as unevaluated. gh run view --log-failed empty or erroring: report the unread run, continue triaging the remaining failed checks, and mark the unread run untriaged in the plan. CI still running: report the partial state and stop; do not diagnose incomplete checks.
• Logs do not identify a root cause (insufficient logs, unreproducible secret or environment failure): report the evidence found; no guessed fix; in autonomous mode push nothing.
• The smallest fix requires widening scope beyond the failing job/step or broadening workflow permissions: stop and report why; never expand permissions to make tests pass.
• Local check does not reproduce the CI failure: do not push. Report the reproduction gap and attach the CI log as the blocked state.
• A fix resolves one check but breaks another: if not yet pushed, amend or discard the fix; if pushed, revert it. Re-triage treating the new break as a root cause.
• Interactive non-convergence: report remaining failures and the diff applied; roll back edited files via VCS when the user requests it.
• Autonomous run still red: diagnose the new failure and apply one further in-scope fix; still failing with no new actionable cause → blocked, with the failing-run link, analysis so far, and the exact failing job. Leave the branch and runs in place; never delete or force-push to hide a failure unless the user asks.
• Push or watch interrupted: the remote branch state is authoritative: re-run gh run list --branch ci-fix/<original-branch> --limit 1 and resume watching; never re-push blindly.
• Push rejected (protected branch, conflict, permission): do not force-push. Report the rejection reason as the blocked state.
• Non-convergent: after repeated fix cycles, new failures keep appearing in the fix's own code. Stop. Report the non-convergent state with the failure chain; do not claim green or that the done predicate holds.
• Sweep flake or ambiguity: the failure does not reproduce locally, or the root cause cannot be isolated to one minimal change: classify non-actionable or hand off with evidence; do not patch.
• Sweep budget exhaustion or breaker trip: the attempt cap is reached, or non-convergence and flakes repeat: stop, hand off with the accumulated evidence and the attempt count, and do not start a new repair or swallow the error.
• Sweep partial result: a worktree repair is never merged; a partial patch is returned as a proposal with its verification state, never as a completed fix. The worktree is the only writable sweep surface and may be discarded.

Output

Classify: one chat record with the check name, run identifier, observed failure signal, the single deterministic class, the next owner, and the one-sentence next action; no-CI and blocked states are included as their own classes, never omitted; the reviewable fix plan follows when a PR and gh are available, with untriaged checks explicitly marked and no code changes applied. Fix interactive: failing-check report (check name, run URL, log snippet, missing-log notes), then the ordered root-cause record (per root cause: check name, root cause, changed paths), applied diff, local-check results, and the observed current gh pr checks status; terminal local-fix-ready, blocked with the exact reason, or non-converged. Fix autonomous: the ordered root-cause record plus a summary in fixed order: failing run (link or ID), root cause, fix (what changed), verification (new run link showing green); terminal checks-pass, blocked (exact reason), or non-passing (link and analysis). Sweep: a terminal classification per swept check, reproduced (with the minimal verified patch as a proposal, verifier evidence, and the attempt count), non-actionable (handoff record with the accumulated evidence), or blocked (stopping reason and accumulated evidence).