PR Splitter
Preserve the original PR as source material, build smaller reviewable PRs intentionally, and track drift locally as review feedback changes the stack.
Required workflow
Snapshot before touching history
- Check
git status.
- Create an immutable local reference to the original branch:
git branch backup/original-large-pr.
- Do not delete or rewrite the original branch until the split is complete.
Inventory the original PR
- Inspect
git diff --stat <base>...HEAD, git diff --name-only <base>...HEAD, and git log --oneline <base>..HEAD.
- Classify changes by review unit: prep/refactor, API/type changes, behavior, tests, docs, cleanup, generated/lock files.
Create a local scratchpad
- Write split notes to an uncommitted local file, preferably
.notes/pr-split.md.
- Ensure
.notes/ is ignored or leave it untracked. Do not commit scratchpad notes unless the user explicitly asks.
- Track: original branch, base branch, planned PRs, files/hunks extracted, verification per PR, remaining original diff, and intentional drift from review feedback.
Choose the split shape
- Use stacked PRs when later work depends on earlier work.
- Use parallel PRs only when changes are truly independent.
- Use foundation + parallel follow-ups when one shared prep change unlocks independent work.
Extract changes safely
- Prefer fresh branches from the correct base plus selective restore over rewriting messy history.
- Use path-level extraction for clean file ownership:
git checkout backup/original-large-pr -- path/to/file.
- Use hunk-level extraction for mixed files:
git restore -p --source backup/original-large-pr -- path/to/file.
- Keep each PR independently buildable and reviewable.
Verify each PR independently
- Run the narrowest relevant build, typecheck, lint, and tests for that PR's scope.
- Do not leave tests, docs, or generated files separated from the code they validate unless the split plan explicitly calls for it.
Manage drift deliberately
- Treat reviewer-approved changes as the new source of truth for the stack.
- After changing an earlier PR, rebase dependent PRs onto it and resolve conflicts in favor of the reviewed direction, not blindly in favor of the original branch.
- Compare the evolving stack against
backup/original-large-pr to find remaining intent, not to force byte-for-byte equality.
- Record intentional differences in
.notes/pr-split.md.
Use range-diff for rewritten stacks
- Use
git range-diff after rebases, conflict resolution, or force-pushes to understand what changed.
- Summarize meaningful range-diff results for reviewers when updating a stacked PR.
PR description pattern
Keep PR descriptions concise and reviewer-facing:
## Summary
This is PR N of M split from a larger change.
## Scope
- ...
## Intentionally excluded
- Follow-up PR will handle ...
## Verification
- ...
Do not put the full split ledger in PR descriptions. Keep detailed extraction notes and drift tracking in .notes/pr-split.md.
Scratchpad template
# PR split scratchpad
Original branch: backup/original-large-pr
Base branch: main
## Planned PRs
1. branch-name
- Scope:
- Files/hunks extracted:
- Verification:
- Changeset: (package names, bump type, scoped message)
- Status:
## Remaining original intent
- ...
## Drift notes
- Date / branch / reason:
Changesets
Each split PR must carry its own changeset scoped to the changes in that PR. Do not keep the original changeset from the source branch — it covers the full combined change and does not belong in any single split PR.
After extracting changes into a split branch:
- Delete any changeset files carried over from the original branch. These were written for the combined diff and will produce incorrect changelog entries.
- Create a new changeset for each PR using the CLI (see
.mastracode/commands/changeset.md):pnpm changeset -s -m "your scoped message" (--major | --minor | --patch) pkg-name
- Scope the message to that PR's changes only. The changeset message should describe what this specific PR does, not the full original feature.
- Include only the packages actually changed in this PR. If the original changeset listed five packages but this PR only touches
@mastra/core, the new changeset should only reference @mastra/core.
- Match the version bump type to the PR's scope. A prep/refactor PR is typically
patch; a PR introducing new API surface is minor; a PR with breaking changes is major.
Add changeset creation to the scratchpad template under each planned PR's verification checklist so it is not forgotten.
Common failure modes
Avoid splitting by file when behavior spans files, extracting tests without code, leaving follow-up PRs uncompilable, force-pushing without a reviewer summary, deleting the original branch early, reverting review feedback while resolving stack conflicts, and keeping the original branch's changeset in every split PR instead of creating scoped changesets per PR.
Default output
When asked to split a PR, produce:
- proposed PR sequence,
- branch strategy,
- scratchpad path and initial contents,
- extraction commands,
- verification plan for each PR,
- drift-management plan.
1---2name: pr-splitter3description: Use when breaking a large, complex, messy, or hard-to-review pull request into multiple smaller PRs; planning stacked PRs; extracting independent changes from a branch; splitting mixed refactor and behavior changes; managing drift after review feedback; rebasing follow-up PRs as earlier PRs change; or preserving original branch intent while shipping incrementally.4---5
6# PR Splitter
7
8Preserve the original PR as source material, build smaller reviewable PRs intentionally, and track drift locally as review feedback changes the stack.
9
10## Required workflow
11
121. **Snapshot before touching history**
13 - Check `git status`.
14 - Create an immutable local reference to the original branch: `git branch backup/original-large-pr`.
15 - Do not delete or rewrite the original branch until the split is complete.
16
172. **Inventory the original PR**
18 - Inspect `git diff --stat <base>...HEAD`, `git diff --name-only <base>...HEAD`, and `git log --oneline <base>..HEAD`.
19 - Classify changes by review unit: prep/refactor, API/type changes, behavior, tests, docs, cleanup, generated/lock files.
20
213. **Create a local scratchpad**
22 - Write split notes to an uncommitted local file, preferably `.notes/pr-split.md`.
23 - Ensure `.notes/` is ignored or leave it untracked. Do not commit scratchpad notes unless the user explicitly asks.
24 - Track: original branch, base branch, planned PRs, files/hunks extracted, verification per PR, remaining original diff, and intentional drift from review feedback.
25
264. **Choose the split shape**
27 - Use stacked PRs when later work depends on earlier work.
28 - Use parallel PRs only when changes are truly independent.
29 - Use foundation + parallel follow-ups when one shared prep change unlocks independent work.
30
315. **Extract changes safely**
32 - Prefer fresh branches from the correct base plus selective restore over rewriting messy history.
33 - Use path-level extraction for clean file ownership: `git checkout backup/original-large-pr -- path/to/file`.
34 - Use hunk-level extraction for mixed files: `git restore -p --source backup/original-large-pr -- path/to/file`.
35 - Keep each PR independently buildable and reviewable.
36
376. **Verify each PR independently**
38 - Run the narrowest relevant build, typecheck, lint, and tests for that PR's scope.
39 - Do not leave tests, docs, or generated files separated from the code they validate unless the split plan explicitly calls for it.
40
417. **Manage drift deliberately**
42 - Treat reviewer-approved changes as the new source of truth for the stack.
43 - After changing an earlier PR, rebase dependent PRs onto it and resolve conflicts in favor of the reviewed direction, not blindly in favor of the original branch.
44 - Compare the evolving stack against `backup/original-large-pr` to find remaining intent, not to force byte-for-byte equality.
45 - Record intentional differences in `.notes/pr-split.md`.
46
478. **Use range-diff for rewritten stacks**
48 - Use `git range-diff` after rebases, conflict resolution, or force-pushes to understand what changed.
49 - Summarize meaningful range-diff results for reviewers when updating a stacked PR.
50
51## PR description pattern
52
53Keep PR descriptions concise and reviewer-facing:
54
55```markdown
56## Summary
57
58This is PR N of M split from a larger change.
59
60## Scope
61
62- ...
63
64## Intentionally excluded
65
66- Follow-up PR will handle ...
67
68## Verification
69
70- ...
71```
72
73Do not put the full split ledger in PR descriptions. Keep detailed extraction notes and drift tracking in `.notes/pr-split.md`.
74
75## Scratchpad template
76
77```markdown
78# PR split scratchpad
79
80Original branch: backup/original-large-pr
81Base branch: main
82
83## Planned PRs
84
851. branch-name
86 - Scope:
87 - Files/hunks extracted:
88 - Verification:
89 - Changeset: (package names, bump type, scoped message)
90 - Status:
91
92## Remaining original intent
93
94- ...
95
96## Drift notes
97
98- Date / branch / reason:
99```
100
101## Changesets
102
103Each split PR must carry its own changeset scoped to the changes in that PR. Do not keep the original changeset from the source branch — it covers the full combined change and does not belong in any single split PR.
104
105After extracting changes into a split branch:
106
1071. **Delete any changeset files carried over from the original branch.** These were written for the combined diff and will produce incorrect changelog entries.
1082. **Create a new changeset for each PR** using the CLI (see `.mastracode/commands/changeset.md`):
109 ```bash
110 pnpm changeset -s -m "your scoped message" (--major | --minor | --patch) pkg-name
111 ```
1123. **Scope the message to that PR's changes only.** The changeset message should describe what this specific PR does, not the full original feature.
1134. **Include only the packages actually changed in this PR.** If the original changeset listed five packages but this PR only touches `@mastra/core`, the new changeset should only reference `@mastra/core`.
1145. **Match the version bump type to the PR's scope.** A prep/refactor PR is typically `patch`; a PR introducing new API surface is `minor`; a PR with breaking changes is `major`.
115
116Add changeset creation to the scratchpad template under each planned PR's verification checklist so it is not forgotten.
117
118## Common failure modes
119
120Avoid splitting by file when behavior spans files, extracting tests without code, leaving follow-up PRs uncompilable, force-pushing without a reviewer summary, deleting the original branch early, reverting review feedback while resolving stack conflicts, and keeping the original branch's changeset in every split PR instead of creating scoped changesets per PR.
121
122## Default output
123
124When asked to split a PR, produce:
125
1261. proposed PR sequence,
1272. branch strategy,
1283. scratchpad path and initial contents,
1294. extraction commands,
1305. verification plan for each PR,
1316. drift-management plan.
mastra-ai