pr-dev

pr-dev

Drive a pull request from open → review addressed → CI green → merge-ready, then stop and wait for explicit user approval before merging.

Why this skill exists

After a PR opens, the real work is staying on top of CI failures, reviewer threads, and merge conflicts — often across many minutes. A one-shot "check and report" leaves the PR stalled whenever a simple retry or two-line fix would have unblocked it, and it misses threads that arrive after the initial check.

This skill runs a persistent drive loop — re-fetch, act, push, loop — so you never babysit GitHub tabs. It stops at exactly two states: ready (asks for approved) or blocked (asks for help).

Inputs

Resolve once at startup; reuse throughout:

Input	Resolution
No argument	gh pr view --json number -q .number from current branch
PR number 42	Use directly
PR URL	Extract number from URL

If no PR resolves, ask and stop.

Hard rules

These rules exist because past implementations broke in the specific ways listed.

• Re-fetch before every decision — cached state causes wrong merge-readiness calls after fast CI flips.
• Never stop on an idle poll — CI is often queued a few seconds after the push; one clean poll ≠ done.
• Never push to any branch other than the PR head branch — avoids touching base or other PRs.
• Never prefix commits with [skip ci] — required checks must run; skipping forces admin-bypass merges.
• State every review reply in conversation before posting — user may redirect the tone or content; surprises erode trust.
• Never change tests/CI config to silence a flaky failure unless logs prove it's branch-related.
• Never retry a flaky run more than 3× — after that it's an infra problem requiring human judgment.
• Always restart the loop immediately after any push — a push triggers new CI; stopping now abandons the run.
• Never call gh pr merge until the user writes approved in this conversation — protects against accidental merges.
• Never use --admin unless the user explicitly authorizes it.

Core drive loop

startup:
  resolve PR number and REPO
  HEAD = pr head branch name

loop:
  state = bash $CLAUDE_SKILL_DIR/scripts/fetch-pr-state.sh $PR
  if PR merged or closed → report; STOP

  # Review threads
  unresolved = threads where isResolved==false and isOutdated==false
  for each thread:
    read body; assess: agree / partially agree / disagree
    state reply text in conversation          ← user can redirect
    post reply via gh api
    if agreed/partial: apply code fix; commit; push
    bash $CLAUDE_SKILL_DIR/scripts/resolve-thread.sh $THREAD_ID
  if any thread needed a push → restart loop immediately (no sleep)

  # CI
  if any check failing:
    RUN_ID = first failed run for current HEAD commit
    gh run view $RUN_ID --log-failed   → classify (table below)
    branch-related  → patch, commit, push; restart loop
    flaky, retry<3  → gh run rerun $RUN_ID --failed; retry++; restart loop
    flaky, retry≥3  → surface to user; STOP (blocked)
    infra/unrelated → surface to user; STOP (blocked)
  if any check pending/queued → wait (cadence below); restart loop

  # Readiness
  if all checks green AND unresolved==0 AND mergeStateStatus==CLEAN:
    print readiness summary; STOP — wait for `approved`

  sleep(cadence); restart loop

Fetch fresh state

bash "$CLAUDE_SKILL_DIR/scripts/fetch-pr-state.sh" "$PR"

Quick snapshot inside the loop:

gh pr view "$PR" --repo "$REPO" \
  --json number,title,state,mergeable,mergeStateStatus,\
reviewDecision,statusCheckRollup,headRefOid,headRefName

Address a review thread

1. Read the full thread body — understand what the reviewer is asking.
2. Assess and state in conversation: agree, partially agree, or disagree.
3. State the reply (user can redirect before it's posted). Use $CLAUDE_SKILL_DIR/templates/review-reply.md.tmpl shapes.
4. Post the reply:

   gh api "repos/$REPO/pulls/$PR/comments" \
     -X POST -f body="$REPLY" -f in_reply_to="$COMMENT_ID"
   

5. Fix code if agreed or partially agreed.
6. Resolve the thread:

   bash "$CLAUDE_SKILL_DIR/scripts/resolve-thread.sh" "$THREAD_ID"
   

7. Commit and push all fixes; then restart the loop.

Diagnose a CI failure

RUN_ID=$(gh run list --repo "$REPO" \
  --commit "$(gh pr view $PR --repo $REPO --json headRefOid -q .headRefOid)" \
  --json databaseId,conclusion \
  --jq '.[] | select(.conclusion=="failure") | .databaseId' | head -1)
gh run view "$RUN_ID" --repo "$REPO" --log-failed

Classify CI failures

Signal in logs	Classification	Action
Test/lint/compile error in a PR-touched file	Branch-related	Patch, commit, push; restart loop
runner provisioning failed, network timeout, registry error	Flaky/infra	gh run rerun $RUN_ID --repo $REPO --failed (max 3×)
Dependency outage, GH Actions infra error	Unrelated	Surface to user; STOP
Ambiguous	Ambiguous	One manual diagnosis; then decide

Push a fix

git add -p                    # stage only the relevant change
git commit -m "fix: <what and why>

Co-Authored-By: Claude <[email protected]>"
git push origin HEAD

Then restart the loop immediately — never treat a push as a terminal outcome.

Wait for CI

For short cycles: gh pr checks "$PR" --watch

For long cycles (5+ min) or when other work can run in parallel, use the Monitor until-loop. See $CLAUDE_SKILL_DIR/references/ci-monitor-loop.md.

Polling cadence

State	Interval
CI pending/queued/running	60 s
Fix just pushed	Immediate restart — no sleep
CI green, threads still open	45 s
All green + 0 threads	Readiness gate — STOP

Readiness gate

Confirm ALL before printing:

• All CI checks green (no pending, no failing)
• 0 unresolved review threads (re-run fetch-pr-state.sh)
• mergeStateStatus is CLEAN
• PR is not behind the base branch

Print:

PR #N is ready to merge.
  ✓ N/N CI checks green
  ✓ 0 unresolved review threads
  ✓ Branch up to date with base

Reply `approved` to squash-merge and clean up.

Do not call gh pr merge until the user writes approved.

Merge and clean up (after approved)

gh pr merge "$PR" --squash --delete-branch

Close issues linked in the PR body (Closes #N, Fixes #N):

gh issue close <N> --comment "Shipped in PR #$PR."

Then clean up the local environment:

bash "$CLAUDE_SKILL_DIR/scripts/cleanup-after-merge.sh" "$PR"

Blocked state

Surface clearly, then stop:

Blocked on PR #N — need your input:

Issue: <specific description of what can't be resolved>
Options:
  A) <option>
  B) <option>

Which do you prefer?

Never silently stop, guess, or take a destructive action without confirmation.

Anti-patterns

Wrong	Right
Stop on one idle poll	Keep looping — CI may still be queued
Stop after pushing a fix	Restart loop immediately
Retry a flaky runner 10×	Max 3×; then surface to user
Post reply without stating it first	State in conversation; then post
Merge without explicit approved	Stop at readiness gate; wait
Patch CI config to silence flaky test	Retry; escalate if it persists
Batch unrelated fixes in one commit	One commit per logical fix

Output format

• Progress updates: brief, state-change only (not every poll tick)
• On fix push: Pushed fix: <what> (SHA abc1234). Resuming.
• On flake retry: Retried flaky run (attempt N/3). Watching.
• On thread resolved: Thread "<snippet>": agreed/partial/disagree — replied and resolved.
• At readiness gate: full readiness summary above; then stop
• After merge: single-line summary — SHA, checks, fixes pushed, retries, issues closed