Drain a PR queue
A fleet writes PRs faster than a queue drains. When the queue is the goal — get every open PR merged or closed with evidence — the bottleneck is almost never the merges. It is the review gate.
This skill is the recovery playbook for the failure that wedges everything: the LLM review council stops posting formal reviews, so every PR sits unapproved no matter how green its checks are.
When to use
- Triggers: 'merge all open PRs', 'zero open PRs', 'review council not approving', 'vibecodereview failing', 'chair posted no review', 'PR queue backlog', 'unstack PRs', 'approve PRs', 'land a stack', 'secondary rate limit', 'release PR conflicts', 'restack branches'.
- Diagnosing council starvation (metered lens keys capped or out of credit, expired OAuth seats), re-pointing lenses at live seats via the council_models override, and syncing repo secrets to rotating OAuth credentials.
- The rerun trap (a re-run uses the workflow pinned at trigger time; only a fresh synchronize picks up the fix) and the empty-commit kick that needs no checkout.
- A merge loop contract (clean state, latest run per check green, one APPROVED review, delete the head branch so stacked children re-target) and disposal of stacked, oversize and superseded PRs without losing work.
- Landing stacks across new repos: recorded branch tips so
rebase --ontosurvives squash merges, GitHub's secondary content-creation limit, restackingfile:dependencies onto published versions, and the ship-sync branch for a second release.
Diagnose council starvation first
When every council check "passes" or fails fast and no APPROVED review appears,
read the run log before touching anything else:
chair posted no review this run (primary=success, ...)means the chair ran but declined to post — it had zero usable lens reports.- The council comment body carries a base64
carrypayload. Decode it: it lists each lens and its failure —HTTP 403: Key limit exceeded (monthly limit),402credits depleted,not set. That tells you which key died. - A token-probe line (
token_N=live|dead) shows which subscription seats work.
Metered keys die on quotas. Subscription OAuth seats expire or get rate-capped. Diagnose which side is dead before reconfiguring.
Re-point lenses at live seats
The council accepts a council_models CSV override of provider|model|Name|lens
tuples. Providers include the subscription seats (claude, claude2, claude3,
claude4) that shell the CLI on OAuth tokens instead of metered APIs:
council_models: >-
claude2|claude-sonnet-5|Claude Sonnet 5|correctness,
claude3|claude-sonnet-5|Claude Sonnet 5|security
Map each claudeN provider to the matching claude_code_oauth_token_N input.
Ship this as a normal workflow PR — pull_request runs use the head's workflow
file, so the fix PR's own council run exercises the new lenses and is its own
proof.
The rerun trap
gh run rerun re-executes the workflow file pinned at trigger time. A council
failure caused by the old configuration will re-fail identically forever.
Only a fresh pull_request event re-reads the workflow:
synchronize— push to the head branch.review_requested— useless when the repo's only collaborator is the owner (you cannot request the author).opened/edited-style events do not apply unless the workflow listens.
To retrigger without a checkout, mint an empty commit server-side:
tree=$(git rev-parse <headSha>^{tree})
new=$(git commit-tree "$tree" -p <headSha> -m "Retrigger council")
git push origin "$new:refs/heads/<branch>"
Fetch with --filter=blob:none first so this costs tree objects only. Pace the
kicks — each one fires the full check suite. Verify git ls-remote still shows
the listed head before pushing: another worker's force-push makes the kick a
non-fast-forward that must be skipped, not forced.
The inverse also holds: reruns DO re-resolve merge content for checks whose
workflow file is unchanged. Preview, test, and standards failures caused by a
broken base branch are correctly retried with rerun-failed-jobs — the run
re-merges onto the fixed base. Split the two classes: pin-sensitive failures get
kicks, content-sensitive failures get reruns.
Keep secrets synced
Subscription OAuth tokens rotate under a proxy layer (access tokens live hours; refresh tokens rotate on use). Point repo secrets at the proxy's current auth files, not a stale export, and refresh on a loop — a token that was live at push time can be dead by the time the fiftieth council run consumes it.
Probe each seat directly before trusting it; a 429 means rate-capped (it
recovers alone), a 401/403 means dead (rotate or re-login — an org-level
OAuth block cannot be fixed from a CLI).
The merge loop
A PR is mergeable only when all of these hold at the same instant:
mergeable_state == clean- latest run per check name is
success/skipped/neutral— dedupe by name, oldest runs stay in the rollup forever - at least one formal
APPROVEDreview exists (a comment is not an approval)
Merge with squash and delete the head branch. Deleting the head branch is what re-targets any PRs stacked on it onto the default branch — without it they sit on a dead base and can never merge.
Dispose of the backlog by evidence, not by mood
- Empty diff: PR standards itself flags
empty diff— every touched path is already identical on main. Close as superseded; the work landed elsewhere. - Ancestor:
git merge-base --is-ancestor <head> <source-branch>— the head is fully contained in a landing-plan source branch. Construction-grade proof. - Issue closed: the linked issue was closed by a merged PR or by the owner. The PR dies with its issue.
- Duplicate: byte-identical diff to another open PR — keep the cleaner one.
- Stacked: rebase the PR's own net diff onto current main (
merge-baseto find the divergence point; squash-apply the diff when lineage is foreign), force-push, retarget base to main. If a file the PR modifies does not exist on main and arrives via an unmerged parent, the chain is real — land the parent first or mark needs-human. - Oversize: re-measure after unstacking — foreign lineage inflates the counted diff. Still over the cap means split by subsystem, one issue per split.
Land a stacked queue at fleet scale
This part is for the opposite problem: a fleet built many stacked branches locally, across many new repos, and one lead now lands them. It worked for about 370 PRs over 19 repos.
Record the tips before you touch a branch
Write each branch name and its tip SHA to a file before any rename or rebase.
A squash merge puts the parent's change on main as a new commit, so the
child still carries the parent's old commits. Rebase the child onto main
from the parent's recorded tip:
git rebase --onto origin/main <recorded tip of parent> <child>
Without the recorded tip, the rebase replays the parent's commits again and conflicts with their squashed copy.
Stay under the secondary limit
GitHub limits content creation to about 80 requests a minute and 500 an hour.
This secondary limit is separate from the primary limits (5,000 REST requests
and 5,000 GraphQL points an hour). It answers 403 or 429 while
gh api rate_limit still shows a full quota. It counts REST and GraphQL
writes alike, so a change of API does not avoid it. Six repos landing at once
hit it.
- When a response is
403or429, wait for theretry-afterheader if it is present, else at least one minute, before the next write. - Poll check runs with REST on the head SHA every 30 seconds:
gh api repos/<o>/<r>/commits/<sha>/check-runs. - Merge at most about three repos in one round, then wait.
- Keep the merge itself out of the landing script. The script opens the PR and waits for checks. A person or the lead agent reads the result and merges.
Restack file: dependencies onto published versions
Branches built before their sibling packages were on npm depend on them with
file: paths. When the packages publish, replay each branch onto the new base
one commit at a time:
git cherry-pick -n <commit>.- Rewrite each
file:spec for a published package to its range. - Regenerate the lockfile only when
package.jsonchanged. git commit -C <commit>to keep the message and the author.
Commit by commit keeps a tests-first history visible. Stop on a conflict in
any file other than package.json or the lockfile: that is a real conflict.
pnpm writes file: paths to the lockfile as relative paths, so keep the same
relative layout as the main checkout for every worktree.
Ship a second release into a squash-merged branch
When main merges into release by squash, the first main to release PR
is clean. The second one conflicts, because the two branches share no recent
ancestor. Build a sync branch that holds main's exact tree and records
release as a parent:
git checkout -B <prefix>-<issue>-ship-sync origin/main
git merge -s ours --no-edit origin/release
git diff --quiet origin/main && echo "tree equals main"
Caution: -s ours drops every change that exists only on release, for
example a hotfix made there. First run git log origin/main..origin/release.
Each squash commit shows there, so also compare release with the main
commit it last shipped:
git diff --stat <main SHA of the last ship> origin/release
An empty diff means release holds nothing that main lacks. If the diff
shows changes, stop. Port those changes to main first.
Open it against release with a full standard body and its own issue. Some
pre-push guards block any branch whose name contains release, because they
protect release branches. The sync branch is not a release push, so name it
ship-sync.
Budget the seats
Every council run consumes a chair call plus one call per seat lens. A mass retrigger over a hundred PRs will eat subscription quota windows — pace kicks and let the sweeper retry failures rather than fanning out all at once.
Proof still applies
Driving the queue does not waive evidence: visible diffs need real before/after
captures attached to the PR, everything else needs a command and its result in
## How I verified. A council that flags stale proof is usually right — the
branch moved under the body.