Ci Auto Fix

CI Auto-Fix

Diagnose and fix a failed CI check, then verify it passes. Generic across repositories; currently implements the GitHub Actions path via gh.

This SKILL.md is the orchestration index. Load the matching rule file when you need detail — do not preload them.

| Phase | Goal | Required rule | | ----- | ---- | ------------- | | 0 | Resolve the target (run ID / PR URL / auto-detect) | this file | | 1 | Identify the failure (fetch logs) | this file | | 2 | Read every workflow file before editing one | this file | | 3 | Classify the failure with an explicit verdict | [rules/verdicts.md](./rules/verdicts.md) + [rules/self-improvement-loop.md](./rules/self-improvement-loop.md) (read lessons) | | 3.5 | Write the plan artifact + run the confidence gate | [rules/confidence-gate.md](./rules/confidence-gate.md) + [templates/plan-artifact.md](./templates/plan-artifact.md) | | 4 | Apply the minimal, targeted fix | this file + [rules/anti-patterns.md](./rules/anti-patterns.md) | | 5 | Verify locally before pushing | this file | | 6 | Commit and push (rebase-safe) | this file | | 7 | Wait for CI and capture the new result | this file | | 8 | Iterate — with regression detection | [rules/regression-detection.md](./rules/regression-detection.md) + [rules/self-improvement-loop.md](./rules/self-improvement-loop.md) (write on revert) | | 9 | Report (structured exit summary) | this file + [rules/self-improvement-loop.md](./rules/self-improvement-loop.md) (write on outcome) |

Always read [rules/anti-patterns.md](./rules/anti-patterns.md) first. The refusals apply to every phase.

Input

The user provides one of:

• A GitHub Actions check/run URL (e.g. https://github.com/owner/repo/actions/runs/12345678)
• A check run ID or workflow run ID
• A PR URL with failing checks (e.g. https://github.com/owner/repo/pull/42)
• Nothing — if $ARGUMENTS is empty, auto-detect the failing CI for the current branch's PR (see Phase 0).

The argument is: $ARGUMENTS.

Phase 0 — Resolve the target

If $ARGUMENTS is empty, do not ask the user — resolve automatically:

1. Get the current branch:

``bash git rev-parse --abbrev-ref HEAD ``

1. Find the open PR for this branch:

``bash gh pr list --head "" --state open --json number,url,headRepositoryOwner --limit 1 ``

• If exactly one PR is found, use its URL as the PR input and continue to Phase 1.
• If headRepositoryOwner.login differs from the current repo's owner (fork PR), surface that fact to the user before continuing.
• If no open PR is found, fall back to the most recent failed workflow run on this branch:

``bash gh run list --branch "" --limit 10 --json databaseId,conclusion,workflowName \ | jq '[.[] | select(.conclusion == "failure")] | .[0]' ` If a failed run is found, treat its databaseId` as the run ID input.

• If neither resolves (no PR, no failed run), then ask the user.

1. Print the resolved target before continuing:

Auto-detected target: on branch .

Phase 1 — Identify the failure

Based on the input:

1. Run URL or run ID — fetch the failed job logs:

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

1. PR URL — list the failing checks first:

``bash gh pr checks --repo `` Then fetch logs for each failing check.

1. Check suite / check run ID:

``bash gh api repos///check-runs/ ``

Extract and summarize:

• Which job(s) failed.
• The specific error messages and exit codes.
• Which step within the job failed.
• The full error context (surrounding log lines).

Phase 2 — Understand the workflow holistically

Before making any changes, read every workflow file in the repository:

find .github/workflows -name '*.yml' -o -name '*.yaml'

Build a mental model of:

• How jobs depend on each other (needs:).
• What triggers each workflow (on:).
• Shared steps, reusable workflows, composite actions.
• Environment variables and secrets used.
• Matrix strategies.
• Caching strategies.
• Artifact passing between jobs.

This holistic understanding prevents fixes that solve one problem but break another job or workflow.

Phase 3 — Classify the failure (verdict required)

Pick exactly one verdict per failure. The verdict binds behavior; do not skip this step.

Full decision table and per-verdict notes: [rules/verdicts.md](./rules/verdicts.md).

Verdicts at a glance:

• code-bug / workflow-bug / dep-bug / env-bug → continue to Phase 3.5.
• flaky / unsure → escalate. Stop.

Phase 3.5 — Plan artifact + confidence gate

1. Write or update the plan at .agent/{branch}/ci-auto-fix-plan.md using [templates/plan-artifact.md](./templates/plan-artifact.md).

The plan is read-only documentation of intent — the user can pre-empt before any code is written.

1. Run the confidence gate per [rules/confidence-gate.md](./rules/confidence-gate.md):

| Score | Action | | ----- | ------ | | ≥ 90 | Auto-apply. Continue to Phase 4. | | 80–89 | Show the diff, ask once, apply on approval. | |

```

1. Sync with the remote before pushing — a parallel worker may have pushed:

``bash git pull --rebase origin "" ``

If the rebase conflicts, run git rebase --abort, stop, and report the conflicting files to the user. Do not auto-resolve.

1. Push:

``bash git push origin "" ``

1. If the push is rejected as non-fast-forward, rebase and retry the push once.

If the retry also fails, or the rebase conflicts, stop and report. Never --force push from this skill.

Phase 7 — Wait for CI

After pushing, monitor the check:

1. Wait briefly for the workflow to trigger:

``bash sleep 10 ``

1. Find the new workflow run:

``bash gh run list --branch --limit 5 ``

1. Watch the run until completion, bounded at 30 minutes:

``bash timeout 1800 gh run watch ` If timeout expires (exit code 124), run gh run view to capture pending jobs, report them, and escalate. Same bounded-poll pattern as the reviewer-feedback watch loop in [../../workflow/implement-suggestion/rules/watch-mode.md`](../../workflow/implement-suggestion/rules/watch-mode.md).

1. Check the result:

``bash gh run view ``

Phase 8 — Iterate with regression detection

Full decision table: [rules/regression-detection.md](./rules/regression-detection.md).

At a glance:

• Same failure → re-classify in Phase 3.
• Strict subset → continue with the remaining failures.
• New failure that did not exist before → revert the last commit (git revert HEAD && git push) and re-plan or escalate.

Maximum 4 iterations. After 4, escalate with the structured exit summary.

Phase 9 — Report

Always end with a structured summary block, regardless of outcome:

ci-auto-fix run
  Outcome: 
  Original failure: 
  Verdict: 
  Iterations: /4
  Plan: .agent/{branch}/ci-auto-fix-plan.md
  Successful run:            # if green
  Escalation reason:            # if not green

On success, include the original error, the fix applied, confirmation that all checks pass, and a link to the successful run.

On escalation, include what was tried (one line per iteration), what remains, and suggested next steps for manual investigation.

Self-Improvement

/ci-auto-fix gets better across runs through a two-tier lessons loop (fast episodic tier + gated promotion), like autonomous-workflow and fix-bug. It reads ci-auto-fix-lessons at Phase 3 (biasing the verdict and the Phase 8 regression call) and writes at Phase 8 (on a revert — the strongest negative signal) and Phase 9 (on the CI outcome). Lessons are advisory — they never relax the confidence gate, the revert-on-new-failure rule, or any refusal in [rules/anti-patterns.md](./rules/anti-patterns.md).

This loop is deliberately more conservative than the others because the verdict is inferred from CI logs alone: verdict lessons default to the project-shared tier (repo-specific failure shapes are far more reliable than cross-repo generalizations) with a raised promotion bar (seen_count >= 5), and regression lessons are volatile with a 30-day expiry since error signatures churn. A lesson can never authorize a check-weakening or soft-refusal action — those still re-gate on this run. Full contract and the two ci-auto-fix-specific entrenchment guards: [rules/self-improvement-loop.md](./rules/self-improvement-loop.md). persistent-memory is optional; the loop skips silently if absent.

Definition of done

The run is done when ANY of the following is true:

• All checks are green AND the structured exit summary has been printed.
• The verdict was flaky or unsure and the failure was escalated to the user.
• The confidence gate scored < 80 and the fix was not written.
• A regression was detected and reverted, and the user owns the next step.
• --max-iterations (default 4) was reached.

Source & license

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

• Author: mthines
• Source: mthines/agent-skills
• License: MIT

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