---
name: stacked-prs
description: >-
  Ship a change as a light stack of small, dependent pull requests that
  MergeTempo reviews in order. Each PR branches from the previous one and
  targets it; every PR's description carries a mergetempo-stack footer pointing
  at the root PR and listing the whole stack. Use when a change is too large for
  a single reviewable PR, or naturally splits into an ordered sequence of steps
  (e.g. schema → API → UI). Do NOT use for a single self-contained change.
---

# Stacked pull requests

Break a large change into a chain of small PRs, each building on the last, so
each is small enough to review well and MergeTempo can review the stack in
order.

## Mechanic (keep it light)

```
develop ── branch-1 ── branch-2 ── branch-3
            PR #101     PR #102     PR #103
             base:       base:       base:
             develop     branch-1    branch-2
```

- Create each branch **from the previous branch**, not from trunk.
- Open each PR **targeting the branch above it** (#101 → `develop`,
  #102 → `branch-1`, #103 → `branch-2`).
- When a PR merges and its head branch is deleted, GitHub **auto-retargets** the
  next open PR onto trunk. Never rewrite a base by hand.

> The retarget only fires if the merged head branch is deleted — enable
> "Automatically delete head branches", or delete it on merge. Merge the stack
> top to bottom.

## The footer convention (required on every PR in the stack)

End each PR's description with this footer. The HTML comment is what MergeTempo
parses; the list is for human reviewers.

```
<!-- mergetempo-stack root=#<ROOT> order=<N1>,<N2>,<N3> -->
### 📚 Stacked PR — <POSITION> of <TOTAL>

Part of the stack rooted at #<ROOT>. Review in order in MergeTempo:

1. #<N1> — <title 1> → `<base branch 1>`
2. #<N2> — <title 2> → `<base branch 2>`
3. #<N3> — <title 3> → `<base branch 3>`

> Each PR targets the branch above it. As they merge, GitHub retargets the next
> onto `<trunk>` automatically. Please review and merge top to bottom.
```

- `root=#<ROOT>` — the number of the **first PR you opened**; never changes.
- `order=` — every PR number, **root first**, in merge order (no spaces needed).
- Bold the current PR's line and add `(this PR)`.
- Keep `root=` and `order=` in the comment accurate — that is the source of
  truth MergeTempo reads.

## Steps

1. Split the work into an ordered sequence of small, self-contained steps.
2. Create the first branch from trunk, commit, push, open PR #1 targeting trunk.
   Its number is the **root**.
3. For each next step: branch from the previous branch, commit, push, open a PR
   targeting the previous branch.
4. After all PRs exist, do a final pass: set every PR's footer with the same
   `root` and full `order`, and each PR's own `POSITION`.
5. Do not manually change bases after merges — let GitHub retarget.
6. Review the stack in MergeTempo, top to bottom.

## Example (`gh` CLI)

```bash
git switch -c feat/users-schema develop
git commit -am "feat: users schema"; git push -u origin feat/users-schema
gh pr create --base develop --head feat/users-schema --title "feat: users schema" --body-file pr1.md  # → #101 root

git switch -c feat/users-api feat/users-schema
git commit -am "feat: users API"; git push -u origin feat/users-api
gh pr create --base feat/users-schema --head feat/users-api --title "feat: users API" --body-file pr2.md  # → #102

git switch -c feat/users-ui feat/users-api
git commit -am "feat: users UI"; git push -u origin feat/users-ui
gh pr create --base feat/users-api --head feat/users-ui --title "feat: users UI" --body-file pr3.md  # → #103

# Final pass — same root/order on every PR
gh pr edit 101 --body-file pr1.md
gh pr edit 102 --body-file pr2.md
gh pr edit 103 --body-file pr3.md
```

`pr2.md`:

```
<!-- mergetempo-stack root=#101 order=101,102,103 -->
### 📚 Stacked PR — 2 of 3

Part of the stack rooted at #101. Review in order in MergeTempo:

1. #101 — Users schema → `develop`
2. **#102 — Users API → `feat/users-schema` (this PR)**
3. #103 — Users UI → `feat/users-api`

> Each PR targets the branch above it. As they merge, GitHub retargets the next
> onto `develop` automatically. Please review and merge top to bottom.
```