pr-creation

Pull Request Creation Skill

Create or update the PR automatically after completed work. Skip this only when the user forbids it, the branch already has a PR, or the work remains experimental.

Never merge without a direct user instruction. When instructed, enable auto-merge and record the instruction in the PR body. Enable Auto-fix on each new PR, then watch it through closure. Handle several PRs oldest first unless a revert or red-default-branch fix is urgent.

Before writing code, search the tree and existing PRs for prior work. Confirm any claimed base failure against current origin/main.

Always follow this skill before creating any PR — don't skip steps, especially the compress-critique-fix loop.

Bound a PR's FOOTPRINT — combine work until the branch gets large

Combine work onto one branch while that branch stays under ~50 changed files — count them with git diff --name-only "$CLAUDE_CODE_BASE_REF"...HEAD | wc -l. Past that bound, split. Combining is worth doing because every PR boots the full workflow fan-out (~50 workflows here, including the long KVM legs) on a shared, account-wide job-slot pool, so two small PRs cost about twice the CI of one, and each one's required checks queue behind the other's long jobs. That saving stops paying as the branch grows. A large branch touches files the trunk is also touching, so it conflicts before it lands, and each re-resolution spends the whole fan-out again. Measured on 2026-08-21: main took 166 merges in 24 hours across 256 distinct files, at a median of 13 files per merge. A 384-file branch in that backlog re-conflicted faster than its own checks could finish.

• Combine when: the branch stays under the bound AND any one of these holds — the changes are coupled, a reviewer would read them together anyway, their tests share fixtures, or they surfaced from the same task (canonical case: a broad audit's findings). One PR, one CI run, one changelog-fragment set, presented as labeled partitions.
• Split when: the branch would pass ~50 files, a change must land or iterate on its own timeline, or the diff is too large to review coherently. Independence alone is still not a reason to split.
• Exceed the bound when: the change cannot be cut into independently valid pieces — a rename and its call sites. Splitting that opens PRs that do not build on their own, so it stays whole.