A large agent-written PR can contain a real feature, generated files, refactors, and unrelated cleanup in one diff. A reviewer cannot approve it by counting green checks or asking for a longer summary. First preserve the work and identify its independent decisions. Then choose a smaller PR, a stack of dependent PRs, or a reasoned exception for an indivisible change. This guide uses a hypothetical 40-file settings feature; file count is a prompt to inspect, not a universal size limit.
Freeze the branch and inventory the patch
Ask the agent to stop editing and record the PR head, base branch, worktree path, and current status. Read the changed-file list, diff summary, commits, generated artifacts, dependency or lockfile changes, migrations, and deleted tests. Keep the original branch intact until a reviewed replacement exists. A large change might be appropriate for generated code or a mechanical migration, but that does not remove the need to check its source and outcome. GitHub recommends small focused PRs because they make purpose and risk easier to understand; this is a review-capacity decision, not an accusation that the agent's code is wrong.
- Mark files that implement the requested behavior, support it, or are unrelated.
- Identify auth, payments, data, configuration, and test changes for specialist review.
- Record the original acceptance check and the running behavior before moving commits.
Split by decisions and dependencies
For the settings example, the patch may contain a profile API change, form UI, visual polish, and an unrelated lint refactor. The lint refactor can be a separate follow-up or omitted if it was not requested. The API and UI depend on one another but can often form two reviewable layers if the API has a stable contract and tests. A database migration might need to precede both and deserves its own rollback and data review. Do not split solely by an arbitrary number of files: each PR should have a coherent reason, an acceptance check, and a reviewer who can decide it. If two slices cannot build or be understood independently, explain their dependency in a stack.
| Slice | Dependency | Review question |
|---|---|---|
| Profile API and tests | Base branch | Does save enforce ownership and return the agreed result? |
| Settings form and UI checks | Profile API slice | Do success, failure, and retry work in the browser? |
| Unrelated lint cleanup | None | Is it needed for this feature or a separate issue? |
| Generated client output | Source schema or generator | Was it produced by the documented command from reviewed input? |
Choose separate PRs or a stack deliberately
Independent slices can branch from the normal base and be reviewed in any order. Dependent slices can use stacked PRs: GitHub describes a bottom PR against the trunk and higher PRs targeting the branch below, so each layer shows its own diff. GitHub's stacked-PR feature is in public preview and has repository and client requirements; check availability before prescribing its controls. Canopy's v0.3.4 release notes list support for asynchronous stacked PR merges, but the exact installed UI should be tested. If your team does not use GitHub stacks, ordinary dependent branches still need explicit base branches, review order, and careful rebasing. Do not force-push a shared PR history merely to make the page look smaller; coordinate with the PR owner and reviewers first.
- Keep every dependency visible in the PR description and branch base.
- Put foundational contracts below the code that consumes them.
- Preserve a link to the original PR or branch while rebuilding the review sequence.
Have the agent deliver one slice at a time
Give the implementing agent the approved split: slice purpose, allowed files or behavior, starting branch, tests, and stop point. Ask it to prepare the first diff and stop for review before beginning the next. A second agent can review the slice read-only against the original issue, but should cite reachable defects rather than expand scope. In Canopy, verify each agent's checkout, branch, changed files, running app, and PR context; an agent session title is not proof that the files are isolated. If moving existing commits between branches, inspect the resulting diff and test after each move. Do not discard the 40-file branch until all intended behavior is accounted for.
- A smaller diff is only useful if it remains buildable and honest about dependencies.
- Keep generated files with the source change that produces them when the repository requires both.
- Review changed tests for weakened assertions as well as added coverage.
Verify the combined result before the final merge
Each PR needs its own reviewable change and checks on its latest commit. After lower layers merge or update, retest dependent branches against their new base and inspect what changed during a cascade or rebase. Finally run the original settings workflow against the integrated code: a valid save persists, another user cannot edit it, and a failed request permits retry. Check the final diff against the original 40-file inventory so useful work was not lost and unrelated edits did not slip through. The team should record accepted work, deferred cleanup, and who owns the final merge. A neat stack can still ship a broken combined feature if nobody checks the whole path.
- Confirm PR bases and latest checks before approving each layer.
- Re-review affected layers after a lower contract changes.
- Record one integrated user-journey result before calling the feature done.
Copyable resources
Oversized PR split plan
Use with the PR owner before rewriting any published branch history.
Original PR / head / base / worktree: [ ]
Original issue and acceptance checks: [ ]
Changed files grouped by behavior, generated output, tests, config, migration, unrelated work: [ ]
Risky paths and assigned reviewer: [ ]
Slice A: purpose [ ]; branch base [ ]; files/behavior [ ]; check [ ]
Slice B: purpose [ ]; dependency [ ]; files/behavior [ ]; check [ ]
Independent follow-up or rejected scope: [ ]
Stack feature available in this GitHub repo/client? [yes/no/unknown]
Canopy installed version and stacked-PR behavior tested: [ ]
Original branch preserved until: [ ]
Latest checks per PR and integrated user journey: [ ]
Final owner and merge order: [ ]Frequently asked questions
Is a 40-file AI pull request automatically bad?
No. Generated or mechanical changes can be large for a coherent reason. Inspect whether the diff contains one understandable decision, reviewable source, meaningful checks, and a clear owner.
Should I ask the agent to split the PR by file count?
Split by purpose and dependency. An arbitrary file cap can leave half a behavior or generated output in the wrong PR.
When are stacked PRs useful?
When one reviewable change depends on another unmerged change. Each PR targets the branch below it and shows a focused layer. Check GitHub's current availability and your team's merge process.
Can I force-push the original branch after splitting it?
Coordinate with the PR owner and reviewers before rewriting published history. Preserve the original state until replacement branches, diffs, and checks are verified.