github-ci-fix

What this skill does

# GitHub CI Fix

This skill is the single GitHub branch-to-merge skill. Use it when the work is anywhere on the path from local branch state to a merge-ready PR.

It has two modes:

- `inspect` mode: diagnose current PR state, summarize blockers, and stop.
- `fix` mode: create or reuse the PR, then stay in a closed PR-to-mergeable loop until required checks are green and no fixable merge blocker remains.

When the user says to publish a GitHub PR, `fix CI`, `fix failing checks`, `get the PR green`, `make the PR mergeable`, or equivalent, default to `fix` mode. Also use this skill immediately after opening or materially updating a PR when CI and review state are expected to gate merge. Do not stop after one patch if the PR is still blocked.

## Prerequisites

- Require `gh` authentication: run `gh auth status`.
- Use GitHub Actions logs for GitHub-hosted checks.
- For non-GitHub Actions providers, report the external URL only.
- Treat unresolved review threads and review comments as part of the same repair lane when they are still active and plausibly blocking merge.

## Inputs

- `repo`: path inside the repo (default `.`)
- `pr`: PR number or URL (optional; defaults to current branch PR)
- user intent: `inspect` or `fix`
- optional publish intent: stage/commit/push/open PR if a PR does not already exist, or if the branch has unpublished local changes that must be pushed before status can be trusted

## Quick Start

- Preferred inspection command:
  - `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
- Add `--json` for machine-friendly output.
- Review-thread inspection fallback:
  - `gh api graphql -F [email protected] ...`
  - or use an existing repo-local/bundled review-thread fetcher when available.

## Workflow

1. Verify `gh` authentication.
   - Run `gh auth status`.
   - If unauthenticated, stop and ask the user to authenticate.
2. Ensure the branch is publishable.
   - Check `git status -sb`.
   - If on the default branch and the task implies publishing, create a branch such as `codex/{description}`.
   - If local changes are part of the requested PR fix, stage and commit them intentionally.
   - Push the current branch if the remote branch is missing or behind the local branch.
3. Resolve or create the PR.
   - If the user provided a PR number or URL, use it directly.
   - Otherwise try the current branch PR: `gh pr view --json number,url,mergeable,mergeStateStatus,isDraft,reviewDecision,statusCheckRollup`.
   - If no PR exists and the task implies publish/fix-to-merge, create one with `gh pr create`, then continue in the same loop.
4. Inspect the full merge state, not just CI.
   - Read:
     - `gh pr view <pr> --json mergeable,mergeStateStatus,isDraft,reviewDecision,statusCheckRollup,latestReviews,url`
   - Distinguish:
     - required check failures or pending runs
     - unresolved active review threads/comments
     - draft state
     - branch conflicts
     - policy blocks you cannot change from the branch
5. Inspect current failing checks.
   - Preferred: use the bundled inspection script.
   - Manual fallback:
     - `gh pr view <pr> --json statusCheckRollup`
     - `gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha,jobs`
     - `gh run view <run_id> --log`
     - If logs are not available yet, fetch the job archive with:
       - `gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs"`
6. Inspect unresolved review threads/comments whenever the PR is still blocked after CI is green, or when review feedback is clearly part of the merge gate.
   - Prefer the bundled review-thread fetcher:
     - `python "<path-to-skill>/scripts/fetch_comments.py"`
   - Manual fallback: fetch review threads and review comments with `gh api graphql`.
   - Ignore outdated threads unless the same issue still exists in the current diff.
   - Prefer the smallest active, high-confidence fix first.
   - Do not ask the user to choose among routine comment fixes unless the comments are ambiguous, mutually incompatible, or materially change product direction.
7. Classify each blocker.
   - `branch regression`: caused by the current diff or by a new control introduced on this branch.
   - `stale test`: assertion or fixture no longer matches current behavior.
   - `environment/startup gap`: runtime or integration path issue not covered by local lightweight checks.
   - `review-blocker`: active review feedback that can be resolved safely from the branch.
   - `merge-conflict`: branch is not mergeable until base-branch drift is repaired.
   - `policy-blocker`: draft status, missing approval, or repo settings the agent cannot satisfy by editing code.
   - `external`: non-GitHub Actions or provider outside this skill's scope.
8. If in `inspect` mode:
   - Summarize the current merge blockers, whether they are CI, review, conflicts, or policy, and the smallest likely fix.
   - Stop.
9. If in `fix` mode:
   - Pick the highest-leverage fixable blocker autonomously.
   - Priority order:
     1. merge conflicts
     2. failing required checks
     3. active review comments that are still applicable and safe to address
     4. pending required checks after a push
     5. missing PR publication steps needed before status can be trusted
   - Implement the smallest fix that addresses the chosen blocker.
   - Run the closest local verification that matches the touched surface.
   - Push the branch.
   - Wait for the fresh required checks to complete.
   - Recheck the live PR state.
   - If the push created new review comments, new conflicts, or new failing checks, keep looping.
   - Do not stop after push while required checks are pending, failing, or while an active fixable review blocker remains.
   - Stop only when the PR is ready for the user to merge, or when the only remaining blocker is a real non-code blocker you cannot resolve from the branch.
10. Determine merge readiness before exit.
   - Success means all of the following:
     - `mergeable` is not `CONFLICTING`
     - required checks are green
     - no active applicable review thread remains that you should reasonably fix from the branch
     - the branch is not waiting on a fixable code change
   - If the PR is still blocked only because it is draft, missing external approval, or protected-branch policy that requires a human action, state that explicitly and stop.
11. After the PR is ready in `fix` mode:
   - Run `session-introspection`.
   - Capture only preventable friction from the PR-to-mergeable loop.
   - Prefer the narrowest anti-recurrence control: `script`, `lint`, `hook`, `workflow-doc`, or `AGENTS-trigger`.
   - Apply obvious safe controls immediately when practical.

## Guardrails

- Do not treat `fix CI` as `inspect and stop`.
- Do not split PR publication, CI repair, and routine review-comment repair across separate skills.
- Do not claim CI is green without checking the live PR status.
- Do not stop at a green subset of jobs while required checks are still pending.
- Do not stop at green CI if unresolved active review feedback still leaves the PR not ready to merge.
- Do not ask the user which routine review comment to fix first; choose autonomously unless the comments conflict or require product judgment.
- Do not turn one-time external outages into repo policy.
- Prefer repo-owned parity scripts when they exist instead of improvising new local commands.
- If a new control introduced on the branch breaks CI, fix that control before continuing.
- Ignore outdated review comments unless the same defect still exists in the current diff.
- Keep looping until the PR is merge-ready unless a real blocker requires surfacing to the user.
- If the PR is blocked only by human approval or draft status, say that clearly instead of pretending more code changes are needed.

## Bundled Resources

### scripts/inspect_pr_checks.py

Fetch failing PR checks, pull GitHub Actions logs, and extract a failure snippet. Exits non-zero