/ci-fix

name: ci-fix
description: 'Use when "CI is red", "fix the checks", or "make CI green", one check needs classifying, or a bounded sweep runs. Not for deploys, credentials, or rerun-as-fix. Non-CI bugs: use strike-the-root.'

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

| Field | Bound contract | |---|---| | Trigger | Fix: user asks to diagnose or repair failing CI on a PR or branch; autonomous fix only when the user explicitly asks for the fix to be pushed. Classify: a check is failed, absent, pending too long, unstable, or reported unexpectedly and no patch is requested. Sweep: a recurring or requested sweep monitors CI failures over a bounded attempt window. | | Authority | Human-gated: classify is read-only and writes nothing. Fix interactive writes only named source files after plan approval; rollback is version control. Fix autonomous pushes a fix branch, never opens a PR, and is a remote mutation that requires explicit human invocation. Sweep writes one minimal isolated repair in a worktree; rollback is discarding the worktree; it never pushes, merges, or publishes. | | Side effect | Classify: chat output only. Fix interactive: named local source files edited and a local-equivalent check passes; remote CI unchanged. Fix autonomous: a fix branch pushed with the approved change set and a new CI run observed. Sweep: one worktree repair plus one independent verifier run, returned as a proposal. | | Done | Classify: one deterministic failure class supported by observed evidence, a next owner, a one-sentence next action, and a fix plan when a PR and `gh` are available; nothing mutated. Fix interactive: failing checks identified, the approved local fix applied, and every local equivalent passes; return `local-fix-ready` because remote CI is unchanged. Fix autonomous: a new run on `ci-fix/<original-branch>` is green and the ordered root-cause record is delivered; `checks-pass` is claimed only after a green remote run is observed. Sweep: root cause reproduced or classified non-actionable; any patch is minimal, independently verified, and returned as a proposal; retries stop at the configured cap without symptom patching. |

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>/