OpenParable
Skip to content
← Back to skills

PR Splitter

Development
pr-splitter

PR Splitter is an Agent Skill for development published in the crbnos/carbon repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Split a large, messy, or hard-to-review pull request into smaller reviewable PRs (stacked or parallel) without losing any of the original work — snapshot the branch, extract changes non-interactively, verify each PR independently, and track drift as review feedback lands. Use when a PR is too big to review, mixes refactors with behavior changes, or needs incremental delivery. Requires committed work on a branch — commit or stash first.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/crbnos/carbon/blob/HEAD/.ai/skills/pr-splitter/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/pr-splitter, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

pr-splitter — break a big PR into reviewable pieces

The original branch is source material, never a casualty: snapshot it, build smaller PRs from it deliberately, and keep a local ledger of what went where.

Announce at start: "Using the pr-splitter skill — splitting {branch} into smaller PRs."

Never use interactive git commands (git restore -p, git add -i, git rebase -i) — they hang in this environment. Every extraction below is non-interactive.

Step 1: Snapshot before touching anything

git status --porcelain        # must be empty; if not, STOP — commit or stash first
BASE=$(git merge-base origin/main HEAD)
git branch backup/original-$(git branch --show-current)

Do not delete or rewrite the original branch until the split has fully shipped.

Step 2: Inventory the original PR

git diff --stat $BASE...HEAD
git diff --name-only $BASE...HEAD
git log --oneline $BASE..HEAD

Classify every changed file into exactly one review unit:

UnitExamples
prep / refactorrenames, extractions, no behavior change
API / type changessignatures, models, generated types
behaviorthe actual feature/fix logic
testsnew or changed tests
docs / metadataAGENTS.md, docs, changelogs
generated / lockfilespnpm-lock.yaml, generated types

Step 3: Create the scratchpad

Write .ai/scratch/pr-split.md (gitignored — never commit it):

# PR split — {original branch}
Backup: backup/original-{branch} · Base: {BASE sha}

## Planned PRs
1. {branch-name} — scope: … — files/hunks: … — verify: … — status: …

## Remaining original intent
- …

## Drift notes (date / branch / what changed and why)
- …

Step 4: Choose the split shape

SituationShape
Later work depends on earlier workStacked PRs (each branched off the previous)
Changes are truly independentParallel PRs off main
One shared prep change unlocks independent workFoundation PR + parallel follow-ups
UnsureStacked — dependency mistakes surface as conflicts, not broken builds

Rules: never separate tests from the code they verify; never split one behavior across two PRs by file boundary; each PR must build and pass its tests alone.

Step 5: Extract non-interactively

Start each PR from the correct base (main, or the previous PR in the stack):

git checkout -b {pr-branch} {base}

Whole files (the file belongs entirely to this PR):

git checkout backup/original-{branch} -- path/to/file.ts

Part of a file (the file mixes changes for different PRs):

git diff {base} backup/original-{branch} -- path/to/file.ts > .ai/scratch/extract.patch
# Edit .ai/scratch/extract.patch: keep the file header lines (---/+++),
# DELETE every @@-hunk that belongs to a different PR, keep the hunks you want.
git apply .ai/scratch/extract.patch

If git apply fails (context mismatch), do not fight it: open the file and make the wanted changes by hand, using the patch as the reference. Then delete the patch file.

Commit each extraction with a conventional message and check it off in the scratchpad, noting exactly which files/hunks moved.

Step 6: Verify each PR independently

For every PR branch, before opening it:

pnpm exec biome check --write --no-errors-on-unmatched <changed paths>
pnpm exec turbo run typecheck --filter=<pkg>    # per touched package, never whole-repo
pnpm --filter <pkg> test

A PR that only compiles on top of an unmerged sibling is stacked — say so in its description and set its GitHub base branch accordingly.

Step 7: PR descriptions

## Summary
PR {N} of {M} split from {original branch}.

## Scope
- …

## Intentionally excluded (follow-up PRs)
- …

## Verification
- {commands run + results}

Keep the detailed extraction ledger in .ai/scratch/pr-split.md, not in PR bodies.

Step 8: Manage drift as reviews land

  • Reviewer-approved changes are the new source of truth — when an earlier PR changes, rebase its dependents onto it and resolve conflicts in favor of the reviewed direction, never blindly back toward the original branch.
  • After any rebase/force-push: git range-diff {old-tip}...{new-tip} and summarize meaningful differences for reviewers.
  • Periodically diff the stack against the backup to find remaining intent (work not yet shipped in any PR) — not to force byte-for-byte equality.
  • Record every intentional divergence in the scratchpad's drift notes.

Done when

  • Every hunk of git diff $BASE...backup/original-{branch} is either shipped in a PR or explicitly listed in the scratchpad as dropped (with a reason)
  • Each PR builds and passes its scoped gates independently
  • Tests shipped in the same PR as the code they verify
  • Backup branch still intact

Failure modes to avoid

Splitting by file when behavior spans files · extracting tests without their code · a follow-up PR that doesn't compile · force-pushing without a range-diff summary · deleting the backup early · resolving stack conflicts by reverting reviewer feedback.