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

# 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