PR Stack

Pull requests and PR stacks

A stack is a chain, sometimes a tree, of PRs where each PR's base is the previous PR's branch. Reviewers can then read one concern at a time while the work keeps moving. Every PR in a stack carries a Stack section listing the whole stack.

Before anything leaves the machine

• Ask before pushing or opening PRs unless the user said to go ahead. Building and committing locally needs no asking.

• Check each PR on its own. Every branch in the stack must pass by itself, not just the top one:

  • ./scripts/ktlint --check;
  • the app compiles: :app:desktop:compileKotlin, :app:android:compileAlphaDebugKotlin, and iOS (:app:ios:compileKotlinIosSimulatorArm64) when shared or iOS code changed;
  • ./gradlew jvmTest test.

  Never pipe Gradle into tail, because that hides the exit code.

• Behavior changes get a device run. Use the campfire-device-tester agent against the throwaway testbed, never a real server. For data or storage changes, include the upgrade path: install the parent branch's build, set non-default values, then install -r the new build.

• Changelog (see CLAUDE.md):

  • A feature keeps one entry across the whole stack, added by the PR where users first see the change.
  • A bug fix found along the way gets its own entry, in the PR that fixes it.
  • Refactors get no entry, and the PR says so.

• Labels: ignore-db-change for .sq changes that need no migration, and skip-coverage only when the user agrees. Add labels with gh issue edit <n> --add-label ....

Building the stack

• Branch each step from the previous one: git switch -c <next-branch> <previous-branch>. Name branches so they sort by step (refactor/settings-async-1a, -1b, -1c).
• Keep one concern per PR. A fix discovered on the way is its own PR, branched from where it applies, even if that makes the stack a tree.
• Commit signing goes through 1Password and sometimes fails with "failed to fill whole buffer". Tell the user and wait for them to say "retry". Never bypass signing (--no-gpg-sign), and never add Co-Authored-By trailers or session links.

Writing the description

Lead with a short paragraph: what the PR does and why, and which issue it's part of (Part of #607). Then the sections that apply. Recent PRs use:

• What changed: the substance, grouped by area. Name the types and files reviewers should look at.
• What didn't change, for refactors: the behavior, keys or APIs that stayed the same.
• Verification: the exact checks you ran and their results, the on-device results, and anything you excluded and why (for example, native-library tests that can't run locally). Don't claim checks you didn't run.
• Follow-ups: known gaps, and links to the issues filed for them.

Put Closes #N in the top PR of the stack. GitHub only closes the issue when a PR merges into main, which happens once the whole stack has landed. End with the footer the session's attribution instructions give.

Don't write "Stacked on #N" prose. The Stack section says it, and stays true as the stack changes.

The Stack section

Every open PR in a stack gets the same nested list, with each PR indented under its parent and [This PR] marking the PR being viewed. Bare #N references are enough, because GitHub renders them as rich links:

## Stack

- #1189
  - #1195
    - [This PR] #1196
      - #1197
        - #1198
        - #1199

Don't write it by hand. scripts/stack_section.py builds the tree from the open PRs' base and head branches, so it doesn't matter which PR you start from. It keeps the section between hidden <!-- pr-stack:start --> / <!-- pr-stack:end --> markers at the top of each body, replacing it in place on reruns:

python3 .claude/skills/pr-stack/scripts/stack_section.py 1196          # dry run: print each PR's section
python3 .claude/skills/pr-stack/scripts/stack_section.py 1196 --apply  # write the ones that changed

Run it after every change to the stack's shape: a PR opened, merged, closed or retargeted. When only one PR is left, it removes the section.