Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

pr-review-merge

Drive a single pull request to merge-ready across all five criteria (sync, CI, inline comments, conversation, threads), then smart-merge it. Source-agnostic library skill invoked by the /tm, /issues, /fix-pr, and /fix-develop commands and by marathon teammates. TRIGGER when a command or agent needs the PR review-to-green loop or the smart-merge (stale-bot-CR dismissal, auto-merge criteria, UNSTABLE/UNKNOWN handling, merge ordering), or when the user asks to take a PR to green/merge it.

bjcoombs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add bjcoombs/ai-native-toolkit --skill pr-review-merge

About this skill


name: pr-review-merge description: > Drive a single pull request to merge-ready across all five criteria (sync, CI, inline comments, conversation, threads), then smart-merge it. Source-agnostic library skill invoked by the /tm, /issues, /fix-pr, and /fix-develop commands and by marathon teammates. TRIGGER when a command or agent needs the PR review-to-green loop or the smart-merge (stale-bot-CR dismissal, auto-merge criteria, UNSTABLE/UNKNOWN handling, merge ordering), or when the user asks to take a PR to green/merge it.

PR Review-to-Green + Smart Merge

Source-agnostic. Consumers pass: PR number, base branch, and bot-reviewer/CI rules from the project's ## Marathon Configuration (defaults if absent).

Run-completion is gated elsewhere (floor)

This skill takes one PR to merge — a process signal. A green, merged PR is not proof the run's assembled product works, and this skill never certifies run-completion. That is gated by the acceptance-contract scripts the marathon engine invokes, not here: scripts/contract/start_gate.py fails closed at run start unless the contract is frozen before decomposition, scripts/contract/spawn_verifier.py is the sole custody chokepoint that spawns the cold non-implementing verifier against the assembled product, and scripts/contract/complete_gate.py fails closed unless that verifier's completion record validates. Merging here never substitutes for those gates. This note is part of the constitutional floor (FLOOR.md); the retro may propose changes but never self-apply them.

Ready Criteria (ALL must be true)

The PR is merge-ready only when all five are simultaneously true. Re-check from the top after every push — a fix can reopen an earlier criterion.

  1. Branch in sync — no merge conflicts with base branch
  2. CI passing — all checks succeed (or skipped)
  3. All inline comments addressed — see thread resolution rules
  4. No unaddressed conversation comments — actionable feedback responded to
  5. All review threads resolved — no unresolved threads remain

Thread resolution rules: Follow bot reviewer rules from the project's CLAUDE.md Marathon Configuration. Generic defaults:

  • Bot threads: Fix the code and push. Resolve via GraphQL if addressed. Use jq JSON builder (avoids zsh $ escaping):
    jq -n --arg tid "$THREAD_ID" '{"query": "mutation { resolveReviewThread(input: {threadId: \"\($tid)\"}) { thread { isResolved } } }"}' | gh api graphql --input -
    
  • Human threads: Fix the code, reply inline explaining the fix, @mention the reviewer. Do NOT resolve human threads — let the reviewer confirm.

Shell Pitfalls

Never use gh ... --jq with complex filters. Always pipe to jq separately.

Use positive jq filters, not negative. zsh escapes != to \!=, breaking filters silently:

# WRONG: gh pr view --json reviews --jq '.reviews[] | select(.state != "APPROVED")'
# WRONG: gh pr view --json reviews | jq '.reviews[] | select(.state != "APPROVED")'
# RIGHT:
gh pr view --json reviews | jq '.reviews[] | select(.state == "CHANGES_REQUESTED")'

Review Loop (each iteration)

Step 1: Sync with base branch (FIRST, every iteration)

BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
git fetch origin $BASE && git merge origin/$BASE --no-edit
# If conflicts: resolve them, commit, push
# If can't auto-resolve: report blocked with details

Resolving a .claude-plugin/plugin.json conflict (the common one in multi-PR waves). The conflict is not always confined to .version — a sibling PR may also have reframed the marketplace description or another field. A version-only line edit (sed-ing just the version line, or a regex that targets only .version) silently keeps the stale side of every other field and can leave merge markers behind. Resolve the whole file deterministically: take the side carrying the siblings' already-merged field changes (usually base), then overwrite only the version with jq:

git checkout --theirs .claude-plugin/plugin.json   # base side, which has the merged siblings' description/other-field edits
jq --arg v "<your-next-version>" '.version = $v' .claude-plugin/plugin.json > /tmp/pj && mv /tmp/pj .claude-plugin/plugin.json
git add .claude-plugin/plugin.json

Always git diff the full plugin.json before resolving — never assume the only divergence is the version line.

Conflict resolution patterns:

  • Import/route files (e.g., App.tsx, index.ts): Accept BOTH sides — additions are additive
  • Barrel exports (e.g., shared/index.ts): Accept both sides — each adds its own export
  • Config/manifest files: Accept both sides unless the same key is modified differently (then ask)

Step 2: Check all criteria - delegate CI to background agent

PR=$(gh pr view --json number --jq '.number')

Spawn a background agent to watch CI (never block on CI yourself):

Agent(
  run_in_background: true,
  prompt: """
  Monitor PR #$PR for CI completion and review state.

  1. Block on CI: `gh pr checks $PR --watch --fail-fast`
  2. When CI settles, gather:
     - CI result: `gh pr checks $PR --json name,state,conclusion`
     - Unresolved threads: `gh api graphql ...` (all unresolved with path/line/author/body)
     - Conversation comments: `gh pr view $PR --comments --json comments`
     - Pending checks count
  3. Return structured report.
  """
)

While CI runs (you are FREE), do an immediate check for threads and comments:

# Quick thread check - fix what you can now
# Substitute the repo owner/name the consumer passed in.
gh api graphql -f query='query { repository(owner: "<owner>", name: "<repo>") {
  pullRequest(number: '$PR') { reviewThreads(first: 50) { nodes {
    id isResolved path line comments(first: 1) { nodes { author { login } body } }
  }}}}}' --jq '.data.
Read the complete source ↗