fix-ci

name	fix-ci
description	Fix failing CI when the user asks for a CI repair or a required check goes red during PR work. Establish causal ownership before editing: repair current-PR failures in place, isolate target-branch regressions in a separate worker and PR, classify provider incidents and flakes without inventing code changes, then state merge order and confidence.

Fix CI

A red check is routing evidence, not ownership. Find the causal owner before changing code.

1. Freeze the failure

1. Read the repository instructions and inspect the current worktree, branch, dirty state, active PR, target branch, and stack.
2. Run the CI provider's cheapest auth and connectivity preflight. For GitHub, use gh auth status plus one read-only API probe. Treat keyring, sandbox, DNS, connectivity, and provider 5xx failures as environment failures; refresh credentials only after a host-capable request returns a confirmed authentication rejection.
3. Snapshot the live PR head, base, state, mergeability, checks, and review state before mutation.
4. Read the failing job's annotations and logs. Record the exact workflow, job, run URL, head SHA, failure text, and first actionable frame. Inspect external-provider checks through their own evidence surface when available; otherwise retain their URL and mark the missing evidence.

This step is complete when every red required check is accounted for and its evidence is tied to an exact SHA. A check name or red badge alone is not a diagnosis.

2. Prove the causal owner

Compare the failing head with the PR diff, its merge result, the target branch, recent target-branch runs, and any existing repair PR. Classify each failure as exactly one:

• current-pr — the current diff introduced the defect, carries stale code incompatible with the target, or needs a branch-local conflict/build repair.
• target-branch — the same failure exists on the target branch or merge baseline independently of the current PR, commonly because another PR merged broken code.
• existing-fix — another open PR or a newer target-branch commit already owns the exact repair.
• external — the repository is healthy and the failure belongs to a runner, provider, network, quota, or dependent service.
• flaky-or-unknown — evidence is insufficient or the failure is not reproducible. Retry the exact failed job once when the provider evidence supports a flake hypothesis; preserve the original evidence.

Use behavioural and provenance evidence, not file-name overlap. A failure can look unrelated to product intent yet still be fallout caused by the current PR. Conversely, a failure displayed on a PR can be inherited from red main.

This step is complete only when the classification has three proofs: the failing log, the relevant source or configuration seam, and a comparison against the target branch or owning change.

3. Repair at the owner

Current PR

Fix the failure on the current PR branch. Keep the repair inside the PR when its diff or branch compatibility is causal. Rebase or merge the target branch only when that is the repository's required branch-update strategy and the owning upstream fix is already there.

Run the exact failed check locally where possible, then the repository's required gates scoped to the diff. Re-read the live PR state and head immediately before a normal push; stop on an unexpected head move. Recheck CI on the pushed SHA.

Target branch

Preserve the feature worktree. Dispatch an isolated worker or session with its own worktree and a branch from the latest target branch. The isolated worker must:

1. reproduce the target-branch failure;
2. implement the narrow causal fix;
3. run the failed check and repository gates;
4. open a separate repair PR that links the affected PR and explains why the feature diff is not causal;
5. complete the repository's current-head review loop.

If isolated workers are unavailable, create the separate worktree and repair PR in the current session. Never mix a target-branch repair into an unrelated feature PR.

Existing fix

Do not duplicate it. If the repair PR is open, establish the order: merge the repair first, update the blocked PR from the repaired target, then rerun its exact-head CI. If the repair is already on the target branch, update the current PR and verify rather than adding another fix.

External or flaky

Keep source unchanged. Retry, monitor, or route the provider incident with the captured evidence. An unknown failure remains a blocker to confidence until it becomes reproducible, passes on retry with a defensible flake diagnosis, or is owned by the provider.

4. Decide merge impact

Report two separate verdicts:

• Causality — whether the current PR caused the failure.
• Mergeability — whether policy and branch protection currently permit merge.

A target-owned failure may leave the current PR's code sound while still blocking the merge mechanically. Say that plainly. When the separate repair unblocks a required check, ask the user to merge the repair first or apply the user's recorded merge preference.

Never auto-merge the feature PR as a side effect of fixing CI. An isolated CI-repair PR may be auto-merged only when all of these are true:

• the user has explicitly recorded that preference;
• the repair is narrow and does not change product behaviour, schema or production data, permissions, security posture, migrations, or release semantics;
• required checks are green on the exact head;
• the repository's current-head autoreview loop has no accepted actionable findings;
• all review threads are dispositioned, the PR is mergeable and current with its base, and merge confidence is high.

When no preference exists, ask once when the first isolated repair PR reaches that gate: whether to auto-merge eligible CI-repair PRs or always ask. Offer to store the answer for future runs; store it only on an explicit request.

After a repair merges, verify the target-branch run. Then update and rerun any PR it blocked.

5. Close the loop

Report:

• the causal-owner classification and its three proofs;
• the repair location, PR, branch, and exact head SHA;
• checks and local gates run, with results;
• current-head autoreview and unresolved-thread state;
• causality, mergeability, and required merge order;
• the remaining blocker or single user action, if any.

Continue until the original failing CI is green on the appropriate exact head, or a named external or human-authority blocker prevents further progress.