ci-fix

CI fix

Repair failing CI on a PR or branch. Two modes: interactive (default, reversible local) and autonomous (remote push, entered only on an explicit user ask). 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	Interactive: user asks to diagnose or repair failing CI on a PR or branch. Autonomous: user explicitly asks for the fix to be pushed.
Authority	Interactive: reversible local — write only named source files after plan approval; no remote mutation. Autonomous: the only remote mutation is creating or updating ci-fix/<original-branch> on the same remote; never opens a PR.
Side effect	Interactive: local source files are edited and a local-equivalent check passes; remote CI is unchanged. Autonomous: a fix branch is pushed with the approved change set and a new CI run is observed.
Done	Interactive: failing checks identified, the approved local fix is applied, and every local equivalent passes; return local-fix-ready because remote CI is unchanged. 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.

Inputs

• 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; 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.

Procedure — interactive (spine)

1. Verify gh authentication: gh auth status. If unauthenticated, stop and ask the user to run gh auth login; no mutation before this. Done when: an authenticated identity is confirmed by gh auth status output, or the handoff is asked and no mutation has occurred.
2. 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: one failing run is identified by its run ID and branch name from command output.
3. Inspect failing checks (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 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 run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha and gh run view <run_id> --log; for one failing job use gh run view <run-id> --log --job <job-id>; 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.