Shepherd pull requests from open to merge-ready

Babysit a PR carries a GitHub pull request or GitLab merge request through its bot review rounds, from just opened to nothing left unanswered, without the human having to refresh the page. The agent verifies each finding, fixes what blocks, replies inside each thread and resolves it. It is a community skill from amElnagdy/review-skills under the MIT license. It requires an authenticated gh (GitHub) or glab (GitLab), plus jq and bash. Review bots sample the diff and every push mints a new round, so an unattended PR piles up half-answered threads and a real bug in round three gets buried under nitpicks from earlier rounds. This import is docs-only: the thread harvester script is not bundled, and fixes go only to the PR branch, never to a merge.

Three rules matter most. Verify before you believe: a bot's severity badge is a guess, so every finding, including the P1s, is a claim to check against the code, since bots are often right and confidently wrong often enough that unexamined suggestions add bugs. Every thread gets an answer: a finding that was fixed, rejected or deferred is closed only after saying so in that thread and resolving it, because silence reads as ignored. Publish before you answer: a "fixed" reply is true only once the remote branch carries the fix, and rejections need no push.

Harvest the round. Findings arrive on two surfaces and a round that reads only one silently misses half. Inline review threads (where Codex and debate-review post, each with a thread_id to resolve and a reply_to to reply in the thread) and top-level review bodies (where Greptile summarizes and debate-review posts round summaries, answered with one PR comment per round). A harvest script returns both correlated in one call:

"<skill-dir>/scripts/threads.sh" <N> > /tmp/pr-<N>-round-<k>.json

Never trust a filtered count without its unfiltered twin: print raw totals before applying any jq filter, and treat a filter that removes everything as broken until the field names are checked. Never describe an object that was not fetched; an empty query means "I can't see it", not a guess. Inline thread replies arrive wrapped in zero-byte COMMENTED review objects, so a "new review" event may be only a wrapper. Diff each round against the previous one, treat outdated: true as a sign the finding may already be fixed, and read a comment_count bump as a bot follow-up. To know whether a reviewer saw the current push, only trust a field that names a sha (GitHub's commit_id compared with head, or debate-review's debate_head); on GitLab say "coverage unknown". Bots count as reviewers when author_bot is true, and threads with a debate-review marker are reviewer threads even though the author is the PR author. Anything else from the PR author and every human comment is out of scope for autonomous fixing and is surfaced to the user. Bots post 5 to 10 minutes after a push, so do not poll tightly, and an unavailable reviewer never blocks acting on the ones that posted, but the gap is disclosed.

Classify by real impact. Blocking means a real bug or broken edge case, a security, authorization, integrity or data-loss exposure, a violation of the change's own contract or acceptance criteria, a migration or schema hazard, or a failing or newly flaky check. Non-blocking covers naming, structure, docs, test nitpicks, micro-performance and style. Ambiguous findings stay blocking until enough code has been read to demote them, since an over-cautious fix costs minutes while a missed P1 costs a production bug. A contested debate-review thread is a claim with a known counter-argument, verified the same way, with the reply saying which side the code supports.

Fix blockers autonomously. Reproduce first where possible, with a probe that fails before and passes after; make one push per round, not one per finding; run the repository's own gate before pushing; run a matching guard skill if installed; and when disagreeing, prove it with the code path, existing guard or pinning test.

Publish, reply, resolve. Work the whole round in one pass, push once and confirm the remote sha, then close loops: confirmed findings get a reply naming the fix commit, rejected ones get a reply with evidence, and deferred ones get an issue with a link, and each thread is then resolved, never one whose question was not answered. Replies go inside the original thread, using the GitHub REST reply endpoint and GraphQL resolveReviewThread, or the GitLab discussion notes and resolve calls (documented but not yet exercised against a live instance, so a failure means stop and report). Each reply opens with attribution naming the model and the person it writes for, then the verdict and brief evidence.

Use it when a PR or MR has accumulated bot review threads that need verification, fixes, replies and resolution, or when you want to drive a PR through multiple review rounds. Do not use it to merge: the agent never merges on its own initiative.

Non-blocking findings are brought once per round as one batched list with a recommendation each (fix now, open an issue or reject), and approved fixes ride the next consolidated push. One invocation gets the initial harvest plus at most two consolidated repair pushes and two re-review cycles unless the user asks to continue. Re-review is triggered by reviewer: debate-review is a local script (scripts/review-pr.mjs with the PR URL) run in the background (10 to 20 minutes, exit code 3 when the head was already reviewed).

Codex is a GitHub app summoned by mentioning @codex review and answers 8 to 15 minutes later, and Greptile-style bots re-review on their own. Wait at most 10 minutes beyond a bot's usual window before marking it unavailable. Rounds should shrink; a round as large as the first signals a systemic problem. At the budget boundary, hand off the remaining findings, unresolved threads, last reviewed sha and unavailable reviewers, and never call an unreviewed head clean.

The merge gate is a clean round from the primary reviewer on the exact final head: Codex saying so plainly, or, for debate-review, a round body whose debate_head equals the final sha with zero agreed and contested findings and no unresolved reviewer threads. Silence is not a pass, and the PR's latest comments are re-read before proposing a merge. The final report lists rounds run, blockers fixed with SHAs, findings rejected and why, issues filed, unresolved threads and CI state, and the user decides whether to merge.

The agent stops and speaks up for a right finding that demands a change far beyond scope, two bots contradicting each other, a recurring finding after a retry, any human reviewer's comment, CI failing for infrastructure reasons, an exhausted repair budget, or a request to stop.

It suits developers and maintainers who use AI review bots and want a disciplined agent to shepherd PRs through review rounds with verified fixes and closed loops.