PR Stack Workflow
Use this for any change too large to review as one pull request: deciding
whether to stack at all, where to cut the slices, the mechanics that keep a
stack reviewable, and how to verify each branch instead of only the tip.
Branch names, commit and PR-title conventions, and how to handle bot review
threads live in git-workflow. Read that first; this skill does not restate it.
Decide whether it needs a stack
A stack costs real time, because every landing forces a base move plus a merge
down the rest of the chain. Pay that only when one of these is true.
| Stack it |
Ship it as one PR |
| You cannot describe the diff in one sentence without the word "and" |
One symptom, one cause |
| It changes a default, or a shape users already have persisted, so it needs a migration decision |
The behavior is new and nobody has state in it |
| Someone will ask "why" and the answer is evidence: numbers, screenshots, a competitor's UI |
The bug report is the justification |
| It touches a shared component other surfaces consume |
The blast radius is one screen |
| Verification is a click path, not an assertion |
An existing test proves it |
Two consequences:
- If the fix is one commit, there is no plan to make. Do not manufacture slices.
- If you cannot yet write the acceptance check, you are researching, not
planning. Do the research, publish it, then plan.
Keep the stack short. Every landing costs another round of retarget-and-merge,
so length is a running cost you pay until the last PR is in.
Slice by what a reviewer has to hold in their head
Not by file, not by directory, not by frontend versus backend. A slice is right
when a reviewer can state what it does, and check it, without loading any other
slice. Practical shapes, in the order they should land:
- The bugs first. Anything true on
main regardless of the wider change.
It is mergeable on day one, it carries no judgment, and landing it early
shrinks everything downstream.
- Defaults and data shape next. A default-visible column, a one-time
migration, "stop rendering an empty string". Cheap diffs with expensive
consequences deserve their own review.
- One screen per slice. A whole component replaced is one reviewer concern
even at 30 files.
- Housekeeping in a bag. Several small independent removals nobody will
argue about.
- One question per slice. "Which run do we compare against?" is one slice:
the query, the picker, the auto-selection, and the URL state together.
- The dense one, alone. There is always one genuinely hard slice. Give it
nothing else to carry.
- New capabilities last but one. A new layout or filter reads as a feature
only once the surface under it has settled.
- Instrumentation last. It wires the seams the earlier slices create. Put
it first and you instrument code that is about to change.
This repo's own agent-setup work is a worked example: #16390, #16391 and #16392
shipped a project-structure path guard as three PRs, landed in that order — the
measured baseline first, then the rules the guard's messages cite, then the hook
that enforces them. The later two are based on the first's branch, not on main,
and #16392's body opens by naming the merge order.
What each PR must say
State the position and the dependency in the body, so a reviewer knows what they
may ignore:
2/8, based on #16913. Base retargets to main when #16913 lands.
- What is deliberately not in this slice, and which slice took it. This is
the line that stops an implementer helpfully widening the scope and breaking
the union check below.
- Any unmerged upstream change that would silently break this slice. A change
that makes two mechanisms read identical data makes them go quiet rather
than visibly wrong, and no test catches that.
Open the whole stack as reviewable, not drafts.
Five rules that cost us
- A fix-up commit lands in the PR that contains the thing it fixes, never as
a follow-up PR later in the stack. Otherwise the earlier PR ships a state you
already know is broken, and it is the one that merges first. When you slice an
existing branch, fold each fix-up back into its parent commit's slice.
- Propagate downward by merging parent into child. Never rebase or force-push
a stack that is under review. Review bots hang their threads off commit
shas, so a force-push discards review you already paid for. These PRs are
squash-merged, so merge commits in a child cost nothing in
main's history.
(The one documented force-push in CONTRIBUTING.md is the CLA author-header
fix on a single PR — not a stack under review.)
- Every PR must stand alone. Lint, typecheck and tests green on its own
branch, not only on the stack tip. A slice that compiles only with its
successor is not a slice: merge it into its neighbor.
- Every landing costs a retarget. When the parent merges, its immediate
child becomes the new bottom: that one PR's base moves to
main, main is
merged into it, and the merge is then propagated down the rest of the chain.
Every landing, until the stack is empty. Plan for that cost instead of
meeting it on merge day.
- A branch that has already merged
main cannot be split by cherry-picking
its commits. The reconciled state exists only in the merged tree: upstream
took some of your changes, replaced others, reverted a few. Slice the final
diff instead, then prove the union.
Prove the union
After slicing a branch, git diff <stack-tip> <original-branch> must be empty,
or every remaining difference must be a deliberate, named decision.
Do not skip this because the slices look right. On an eight-PR split the union
delta came to three files and one added, three removed lines — and that delta was
the finding: the original branch had dropped three ESLint disable pragmas and was
carrying a latent lint failure toward main.
Keep the original branch untouched as the arbiter. When a slice's behavior is in
doubt, run both and compare. Never edit the arbiter to match a slice.
The commands for slicing a merged branch and proving the union are in
references/stack-commands.md, together with the
git-to-PR walk for recovering why a surface is the way it is before you slice it.
Verify per branch, not per stack
Run the verification bar from .agents/AGENTS.md on each branch, in a
worktree checked out on that branch, and publish the result as a table of branch
by check. That file owns the commands and the checks that pass without executing;
follow it there rather than from memory. Three failure modes belong to stacking
specifically:
- Worktrees share one turbo cache. Turbo says so on every run
(
using shared worktree cache), which is exactly why a green lint on slice 4
can be a replay of slice 3's result. Force execution when you switch branches.
- Slicing is what provokes the unused-export gate. Split a feature and you
routinely produce an export whose only consumer lives in a later slice: dead
code on this branch, fine on the tip, and
knip is a required check. The fix
is to move the export into the slice that uses it, not to widen an ignore list.
- Somebody has to load the screen, per slice. Green checks and bot reviews
have between them approved a branch that rendered a blank page, and each slice
has its own branch and its own preview — so a look at the tip proves nothing
about slice 3. Who looks is a judgement call
.agents/AGENTS.md covers: drive
it yourself where the outcome is uncertain, hand over the preview URL where it
is not.
1---
2name: pr-stack-workflow
3description: |
4 Split a large change into a chained stack of small, independently reviewable
5 pull requests, and verify each branch on its own. Use when a change is too
6 large for one PR, when splitting a long-lived branch into PRs, when deciding
7 whether work needs a planning stage at all, when landing or propagating a fix
8 through a stack, or when every check is green on a stack and the change is
9 still wrong.
10metadata:
11 source: https://skillmd.com/skills/langfuse/pr-stack-workflow
12---
13
14# PR Stack Workflow
15
16Use this for any change too large to review as one pull request: deciding
17whether to stack at all, where to cut the slices, the mechanics that keep a
18stack reviewable, and how to verify each branch instead of only the tip.
19
20Branch names, commit and PR-title conventions, and how to handle bot review
21threads live in `git-workflow`. Read that first; this skill does not restate it.
22
23## Decide whether it needs a stack
24
25A stack costs real time, because every landing forces a base move plus a merge
26down the rest of the chain. Pay that only when one of these is true.
27
28| Stack it | Ship it as one PR |
29| --- | --- |
30| You cannot describe the diff in one sentence without the word "and" | One symptom, one cause |
31| It changes a default, or a shape users already have persisted, so it needs a migration decision | The behavior is new and nobody has state in it |
32| Someone will ask "why" and the answer is evidence: numbers, screenshots, a competitor's UI | The bug report is the justification |
33| It touches a shared component other surfaces consume | The blast radius is one screen |
34| Verification is a click path, not an assertion | An existing test proves it |
35
36Two consequences:
37
38- If the fix is one commit, there is no plan to make. Do not manufacture slices.
39- If you cannot yet write the acceptance check, you are researching, not
40 planning. Do the research, publish it, then plan.
41
42Keep the stack short. Every landing costs another round of retarget-and-merge,
43so length is a running cost you pay until the last PR is in.
44
45## Slice by what a reviewer has to hold in their head
46
47Not by file, not by directory, not by frontend versus backend. A slice is right
48when a reviewer can state what it does, and check it, without loading any other
49slice. Practical shapes, in the order they should land:
50
511. **The bugs first.** Anything true on `main` regardless of the wider change.
52 It is mergeable on day one, it carries no judgment, and landing it early
53 shrinks everything downstream.
542. **Defaults and data shape next.** A default-visible column, a one-time
55 migration, "stop rendering an empty string". Cheap diffs with expensive
56 consequences deserve their own review.
573. **One screen per slice.** A whole component replaced is one reviewer concern
58 even at 30 files.
594. **Housekeeping in a bag.** Several small independent removals nobody will
60 argue about.
615. **One question per slice.** "Which run do we compare against?" is one slice:
62 the query, the picker, the auto-selection, and the URL state together.
636. **The dense one, alone.** There is always one genuinely hard slice. Give it
64 nothing else to carry.
657. **New capabilities last but one.** A new layout or filter reads as a feature
66 only once the surface under it has settled.
678. **Instrumentation last.** It wires the seams the earlier slices create. Put
68 it first and you instrument code that is about to change.
69
70This repo's own agent-setup work is a worked example: #16390, #16391 and #16392
71shipped a project-structure path guard as three PRs, landed in that order — the
72measured baseline first, then the rules the guard's messages cite, then the hook
73that enforces them. The later two are based on the first's branch, not on `main`,
74and #16392's body opens by naming the merge order.
75
76## What each PR must say
77
78State the position and the dependency in the body, so a reviewer knows what they
79may ignore:
80
81- `2/8, based on #16913. Base retargets to main when #16913 lands.`
82- What is deliberately **not** in this slice, and which slice took it. This is
83 the line that stops an implementer helpfully widening the scope and breaking
84 the union check below.
85- Any unmerged upstream change that would silently break this slice. A change
86 that makes two mechanisms read identical data makes them go *quiet* rather
87 than visibly wrong, and no test catches that.
88
89Open the whole stack as reviewable, not drafts.
90
91## Five rules that cost us
92
931. **A fix-up commit lands in the PR that contains the thing it fixes**, never as
94 a follow-up PR later in the stack. Otherwise the earlier PR ships a state you
95 already know is broken, and it is the one that merges first. When you slice an
96 existing branch, fold each fix-up back into its parent commit's slice.
972. **Propagate downward by merging parent into child. Never rebase or force-push
98 a stack that is under review.** Review bots hang their threads off commit
99 shas, so a force-push discards review you already paid for. These PRs are
100 squash-merged, so merge commits in a child cost nothing in `main`'s history.
101 (The one documented force-push in `CONTRIBUTING.md` is the CLA author-header
102 fix on a single PR — not a stack under review.)
1033. **Every PR must stand alone.** Lint, typecheck and tests green on its own
104 branch, not only on the stack tip. A slice that compiles only with its
105 successor is not a slice: merge it into its neighbor.
1064. **Every landing costs a retarget.** When the parent merges, its immediate
107 child becomes the new bottom: that one PR's base moves to `main`, `main` is
108 merged into it, and the merge is then propagated down the rest of the chain.
109 Every landing, until the stack is empty. Plan for that cost instead of
110 meeting it on merge day.
1115. **A branch that has already merged `main` cannot be split by cherry-picking
112 its commits.** The reconciled state exists only in the merged tree: upstream
113 took some of your changes, replaced others, reverted a few. Slice the final
114 diff instead, then prove the union.
115
116## Prove the union
117
118After slicing a branch, `git diff <stack-tip> <original-branch>` must be empty,
119or every remaining difference must be a deliberate, named decision.
120
121Do not skip this because the slices look right. On an eight-PR split the union
122delta came to three files and one added, three removed lines — and that delta was
123the finding: the original branch had dropped three ESLint disable pragmas and was
124carrying a latent lint failure toward `main`.
125
126Keep the original branch untouched as the arbiter. When a slice's behavior is in
127doubt, run both and compare. Never edit the arbiter to match a slice.
128
129The commands for slicing a merged branch and proving the union are in
130[`references/stack-commands.md`](references/stack-commands.md), together with the
131git-to-PR walk for recovering why a surface is the way it is before you slice it.
132
133## Verify per branch, not per stack
134
135Run the verification bar from `.agents/AGENTS.md` on **each branch**, in a
136worktree checked out on that branch, and publish the result as a table of branch
137by check. That file owns the commands and the checks that pass without executing;
138follow it there rather than from memory. Three failure modes belong to stacking
139specifically:
140
141- **Worktrees share one turbo cache.** Turbo says so on every run
142 (`using shared worktree cache`), which is exactly why a green lint on slice 4
143 can be a replay of slice 3's result. Force execution when you switch branches.
144- **Slicing is what provokes the unused-export gate.** Split a feature and you
145 routinely produce an export whose only consumer lives in a later slice: dead
146 code on this branch, fine on the tip, and `knip` is a required check. The fix
147 is to move the export into the slice that uses it, not to widen an ignore list.
148- **Somebody has to load the screen, per slice.** Green checks and bot reviews
149 have between them approved a branch that rendered a blank page, and each slice
150 has its own branch and its own preview — so a look at the tip proves nothing
151 about slice 3. Who looks is a judgement call `.agents/AGENTS.md` covers: drive
152 it yourself where the outcome is uncertain, hand over the preview URL where it
153 is not.