Skip to main content

What Are Stacked PRs in AI-Assisted Development

Split a large AI-generated feature into ordered pull requests that reviewers can finish.

Introduction​

Agents produce large diffs easily. Reviewers do not. A single pull request that mixes schema, service logic, and UI forces the reviewer to hold the entire feature in their head. Stacked PRs split that feature into an ordered chain of dependent reviews so each layer shows one coherent increment.

The Graphite-style model popularised this workflow for human teams. AI-assisted development makes it more important, not less, because generation speed outruns review attention. The cost is restacking: when a lower layer changes, every dependent branch must move with it.

This article explains stacks, connects them to Treq stacked workspaces, and covers review flow and team habits that keep the chain maintainable.

Understanding the Concept​

A stacked pull request targets the branch below it instead of always targeting main. The bottom layer targets main. Each higher layer builds on the previous one.

Definition

Stacked Pull Request

A pull request whose branch depends on another pull-request branch, forming an ordered chain of incremental changes for review.

main
└── auth/schema       PR 1 → main
    └── auth/service  PR 2 → auth/schema
        └── auth/api  PR 3 → auth/service

Reviewers see the increment introduced by one layer. They do not need the unfinished upper layers to evaluate the lower contract.

The Graphite-style model adds tooling around that chain: create dependent branches, open PRs with the correct bases, restack after review feedback, and retarget after merges. The philosophy is reviewability through incremental history, not a specific vendor feature list.

Definition

Restack

The ordered rebase of dependent branches after a lower branch or the target branch changes.

AI-generated stacks fail when the agent treats the whole feature as one blob and someone splits the diff afterward by file count. Boundaries should follow contracts: schema before service, service before API, API before UI. Each layer should leave its base buildable and testable.

Treq models the same idea as stacked workspaces. One workspace targets another workspace's bookmark instead of the default branch. When the lower workspace changes, Treq rebases dependents onto the new target. See Workspaces.

Applying It in Practice​

Choose layer boundaries from dependencies, not from a maximum line count. A small migration with a hard contract deserves its own review. A large mechanical rename can stay in one layer.

Create the chain from the bottom up:

git switch main
git pull --ff-only

git switch -c auth/schema
# agent implements schema + tests, then commit

git switch -c auth/service
# agent implements service against schema, then commit

git switch -c auth/api
# agent implements API against service, then commit

Open pull requests with these bases:

auth/schema  → main
auth/service → auth/schema
auth/api     → auth/service

Review from the root upward. Pause upper-layer review when the lower contract is still changing. Restack after lower-layer edits:

git switch auth/service
git rebase auth/schema

git switch auth/api
git rebase auth/service

git push --force-with-lease origin auth/service auth/api

In Treq, create stacked workspaces so each layer has its own working copy and agent session. Auto-rebase updates dependents when a lower bookmark moves. Review each workspace diff before merging from the root upward.

Team tips that prevent reviewer fatigue:

  • Keep stacks to two or three layers unless tooling owns the restack.
  • Assign one stack owner who coordinates force pushes and base changes.
  • Write acceptance criteria per layer, not only for the finished feature.
  • Reject a layer that includes unrelated cleanup from the agent.
  • Re-read the diff after every restack. Conflict resolution can change behavior.

Engineering Considerations​

Use a stack when later work depends on earlier work and one combined PR would be hard to review. Use parallel agents when tasks can merge in any order.

Stack tools automate bookkeeping. They do not choose sound boundaries or resolve semantic conflicts. An agent that rewrites the lower layer during upper-layer work creates churn for every dependent branch.

Squash merges change commit identity on main. Expect to restack remaining layers onto the updated target after a squash. Verify the PR base and displayed diff instead of assuming the hosting platform kept the chain correct.

Scaling and Operational Considerations​

CI should run on each incremental diff and, where integration risk warrants it, on the combined stack. A green upper layer against a stale base is false confidence.

Avoid cross-team stack dependencies unless both teams agree on rewrite policy. A force push to a lower layer rewrites every dependent review.

When branch drift becomes routine, use auto-rebase for AI branches. Safe rebasing still requires conflict review. Automation moves the branch. It does not approve the result.

Next Steps​