# J5ik2o Gh Pr Converge Loop

> Run a convergence loop for GitHub PRs by resolving base-branch merge conflicts first with the j5ik2o-gh-pr-resolve-conflicts skill, addressing unresolved review feedback with the j5ik2o-gh-pr-review-follow-up skill, and fixing failing PR checks. Restart from mergeability after every push until no conflicts or actionable review threads remain and all required checks are green. Use when a pull request must be driven continuously to a merge-ready state.

- Skill: `j5ik2o/j5ik2o-gh-pr-converge-loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add j5ik2o/j5ik2o-gh-pr-converge-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/j5ik2o/j5ik2o-gh-pr-converge-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: j5ik2o (https://skillmd.com/u/j5ik2o)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/j5ik2o/j5ik2o-gh-pr-converge-loop

---


# GitHub PR Convergence Loop

## Trigger

Need to finish a branch or pull request by clearing merge conflicts first, resolving actionable review feedback, and iterating on CI failures until mergeability, review threads, and required checks converge.

Use `gh pr checks` as the source of truth. It includes all PR-attached checks, while `gh run list` only covers GitHub Actions.

## Workflow

1. Resolve the PR and its base branch, then inspect mergeability before review or CI work.
   - If `mergeable` is `UNKNOWN`, wait for GitHub to compute it and query again.
   - Treat `mergeable: CONFLICTING` or `mergeStateStatus: DIRTY` as a blocking conflict.
2. If the PR conflicts with its base branch, fetch and merge the latest base branch to materialize the conflicts locally.
   - When the merge stops with unresolved paths, invoke the `j5ik2o-gh-pr-resolve-conflicts` skill (`$j5ik2o-gh-pr-resolve-conflicts` in Codex or `/j5ik2o-gh-pr-resolve-conflicts` in Claude Code).
   - Let that skill resolve conflicts, validate the build and relevant tests, and stage the resolved files. It must not commit, push, or tag.
   - Inspect the staged resolution, then commit and push it only when the request authorizes those remote writes.
   - After the push, return to step 1 and do not continue until the PR is no longer conflicting.
3. Invoke the `j5ik2o-gh-pr-review-follow-up` skill to inspect unresolved review threads, implement all unambiguous actionable fixes, and obtain any approval that skill requires before replying to or resolving threads.
4. Validate, commit, and push accepted review fixes when the request authorizes those remote writes.
5. Inspect the complete PR check set before waiting.
6. If any check has failed, do not wait for other pending checks. Immediately diagnose the failures and apply the smallest scoped fixes. Run only the fast sanity checks needed to avoid an obviously invalid commit; do not wait for a full local build or test suite. Commit and push the fix immediately so CI restarts as soon as possible.
7. Immediately after every push, start the relevant local build and tests as non-blocking work while CI runs. Continue inspecting CI without waiting for local validation. If local validation fails at any time, diagnose, fix, and push again without waiting for CI.
8. After every push, return to step 1 while local validation continues. Only when no CI check or local validation has failed and at least one check is pending, watch with `gh pr checks --watch --fail-fast`.
9. Finish only when the PR is mergeable, a final thread-aware review read finds no unresolved actionable feedback, the complete required check set is green, and relevant local validation has passed.

## Commands

```bash
# Resolve the active PR and inspect mergeability
gh pr view --json number,url,headRefName,baseRefName,mergeable,mergeStateStatus

# Materialize base-branch conflicts locally
git fetch origin <base-branch>
git merge origin/<base-branch>

# Inspect all attached checks
gh pr checks --json name,bucket,state,workflow,link

# Watch pending checks and fail fast
gh pr checks --watch --fail-fast

# GitHub Actions logs, when the failing check links to a GHA run
gh run view <run-id> --log-failed
```

## Guardrails

- Treat the `j5ik2o-gh-pr-review-follow-up` skill as the source of truth for review-thread actionability and resolution state; do not infer thread state from flat comments.
- Do not inspect review feedback or wait on CI while base-branch conflicts remain unresolved.
- Treat the `j5ik2o-gh-pr-resolve-conflicts` skill as the conflict-resolution and validation workflow. Keep its no-commit, no-push, and no-tag guardrail intact.
- Before the first remote mutation, obtain explicit approval if the request does not already authorize comment replies, thread resolution, commits, and pushes.
- Never wait for pending CI when any failure is already visible. A visible failure is immediately actionable and takes precedence over all pending checks.
- Do not make a full local build or test suite a pre-push gate for a known CI failure. Push the coherent minimal fix first, then run local validation in parallel with the restarted CI.
- Keep each fix scoped to a single failure cause when possible.
- Do not bypass hooks (`--no-verify`) to force progress.
- If the failure is clearly unrelated to the PR and appears fixed on the base branch, merge the latest base branch instead of bloating the PR with unrelated fixes.
- If failures are flaky, retry once and report flake evidence.
- Re-run `gh pr checks --json name,bucket,state,workflow,link` after every push; the check set can change.
- Do not report completion while base-branch conflicts remain unresolved, actionable review threads remain unresolved, or required checks are pending or failing.

## Output

- Merge-conflict status and resolution summary
- Addressed, skipped, and remaining review threads
- Current CI status
- Failure summary and fixes applied
- Commits and pushes performed
- PR URL once review threads are resolved and checks are green