gh-autoreview-resolve

name	gh-autoreview-resolve
description	Run a bounded GitHub automated-review and resolution loop for a specified pull request. Use when Codex must mark a PR ready for review, confirm the automated reviewer started through an eyes reaction, wait for a thumbs-up or concrete review response, validate and address review threads, request a narrowly focused `@codex review` follow-up when warranted, prevent review scope creep through PR comments or an issue-creator follow-up, and optionally merge with the user's preferred strategy.
license	MIT

GitHub Auto Review Resolve

Move one specified pull request from draft through a conservative automated-review loop. Keep the PR's original implementation goal authoritative; do not turn review follow-up into an open-ended audit.

Establish the contract

1. Read repository instructions, the linked issue, PR body, changed files, current head, checks, and existing review threads.
2. Record the original goal, acceptance criteria, explicit non-goals, requested review focus, whether merge is authorized, and the user's preferred merge strategy.
3. Verify gh auth status, the repository, PR number, local checkout, and unrelated working-tree changes before mutations.
4. Run scripts/inspect_review_state.py <PR> --repo OWNER/REPO for a normalized baseline. Treat its GraphQL reviewThreads result as the source of truth for unresolved work.

Do not merge unless the user explicitly requested it. If merge was requested but the strategy is neither stated nor reliably discoverable, ask rather than guess.

Start review

1. If the PR is a draft, run gh pr ready <PR> --repo OWNER/REPO. Do nothing if it is already ready.

2. Record the UTC time immediately before the ready transition and inspect with --after <ISO_TIME> so old bot activity is not mistaken for the new review.

3. Confirm review start from an eyes reaction on the PR or the active @codex review... comment. If feedback or a pass response arrives before eyes is sampled, accept that as a completed start race.

4. If no start signal appears after a reasonable bounded wait, confirm there is no active request, then post exactly one @codex review comment. Never post another request while eyes is present.

5. When the user supplied a review target, request it narrowly:

   @codex review Focus on <specific contract, regression, or risk>.

Avoid leading the reviewer toward a predetermined implementation or inviting a repository-wide audit.

Wait and classify

Poll about every 15–30 seconds and keep the user informed during longer waits. Use the inspection script on every meaningful transition.

• eyes > 0: review is still running; keep waiting.
• thumbs_up > 0: no-issue pass, unless unresolved threads still exist.
• outcome: passed: accept either thumbs-up or an explicit connector response such as “Didn't find any major issues,” provided the response applies to the current head.
• outcome: review_feedback: inspect every unresolved thread.
• outcome: review_response: inspect the response and thread state; do not assume pass or failure.
• outcome: not_started_or_pending: allow short propagation time, then diagnose configuration or request state without posting duplicates.
• outcome: pagination_incomplete or pagination_incomplete: true: fetch the remaining pages before declaring completion.

Check that the review applies to the current head. A stale or outdated anchor is evidence to reassess, not a reason to edit blindly.

Resolve feedback

For each unresolved thread:

1. Reproduce or disprove the claim against current code, tests, runtime behavior, and the PR's original contract.
2. Classify it as:
   • valid and in scope: caused by the PR or violates its acceptance criteria;
   • valid but out of scope: pre-existing or an adjacent enhancement not needed for the PR goal;
   • invalid, duplicate, or stale: contradicted by evidence, already handled, or based on an obsolete head.
3. For valid in-scope findings, make the smallest coherent fix. Preserve unrelated work, follow repository instructions, add focused regressions, and run validation proportional to risk.
4. Commit and push normally. Update the PR body when the new commit materially changes its described behavior or validation evidence.
5. Reply on the exact thread with concise evidence: validity decision, root cause, fix or rejection rationale, tests, and commit when applicable.
6. Resolve the thread only after the reply is posted. Re-fetch the current head, checks, reactions, and unresolved thread count.

Do not silently resolve a substantive thread and do not equate reviewer priority labels with proven validity.

Bound the loop

Use one initial review and at most one explicit focused re-review by default. Request that re-review only when the fix changed a sensitive reviewed boundary, evidence leaves a concrete in-scope doubt, or the user explicitly asked for another pass.

Do not automatically start a third explicit review round. Stop or split follow-up when any of these occurs:

• new comments move beyond the PR's original goal;
• the concern is pre-existing and non-blocking for this PR;
• fixes begin spreading into unrelated modules or architectural redesign;
• the reviewer repeats an already answered behavior without new evidence;
• the acceptance criteria and required regression coverage are already satisfied.

When stopping:

1. If no separate issue is warranted, comment on the PR with the scope decision and evidence, then stop the loop.
2. If the finding is real and deserves implementation, invoke $issue-creator. Research primary evidence, check for duplicates, create an implementation-ready English follow-up issue, comment its link and why it is separated, then stop this review line.
3. If an in-scope release blocker remains unresolved, do not merge. Report the blocker.
4. If only a non-blocking out-of-scope follow-up remains, the PR may proceed after the comment or issue link is recorded.

Finish and optionally merge

Before declaring the loop complete, verify the exact final head, required checks, no active eyes request, and zero unresolved review threads. A pass response is sufficient; do not manufacture extra review rounds merely to obtain a different reaction shape.

If merge was requested:

1. Reconfirm the PR is ready, mergeable, current checks are green, and no in-scope blocker remains.
2. Use the user's preferred method: --rebase, --squash, or --merge.
3. Merge in any user-specified dependency order. Do not delete branches or worktrees unless requested.
4. Re-fetch and report the merged state, resulting commit, linked issue state, and any follow-up issue.

If merge was not requested, stop at the verified ready-to-merge state.

Inspection script

Run from this skill directory:

python scripts/inspect_review_state.py 123 --repo owner/repository
python scripts/inspect_review_state.py https://github.com/owner/repository/pull/123 --after 2026-07-23T00:00:00Z

Use --self-test to validate the script's state classifier without GitHub access.