stack-pr

name	stack-pr
description	Isolate work discovered mid-feature into the next layer of a GitHub stacked PR; branch off the current feature branch, implement to full standard, open the layer's PR against the branch below, link the stack, and carry on.
argument-hint	[one-line description of the discovered work]

Stack a new PR layer on the current feature branch

This skill implements the policy in CLAUDE.md ("Stacked PRs for discovered work"): something has been found mid-feature that must be solved to deliver the objective but is not semantically part of the current branch's work. It gets its own layer in a GitHub native stacked PR (public preview), never folded into the feature branch, never deferred to an issue.

A stack is a sequential chain: each layer branches off the branch below it, each PR targets the branch below it, and only the bottom PR targets main. Merging is bottom-up; merging an upper PR atomically merges everything below it, each PR recorded individually.

If $ARGUMENTS is non-empty, treat it as the description of the discovered work; otherwise derive one from the conversation context. Announce it to the user in one line and proceed; do not ask whether to stack (the policy pre-authorises it). If the work itself is architecturally significant with multiple sensible approaches, the CLAUDE.md "Ask before significant changes" rule applies to the approach, not to the decision to stack.

0. One-time setup

The gh stack CLI is an extension (requires gh 2.90+). The devcontainer installs it automatically (.devcontainer/setup.sh); if it is missing (e.g. the install was skipped because gh was not yet authenticated):

gh extension list | grep -q gh-stack || gh extension install github/gh-stack

1. Park the current work

git status
git branch --show-current

• You MUST be on a feature branch. If on main, stop; there is nothing to stack on.
• If the tree is dirty, commit the WIP to the current branch: git add -A && git commit -m "wip: park work before stacking next layer". Prefer a wip: commit over stashing; squash-merge collapses it on landing, and a stash is invisible to other sessions.
• Push the current branch so the chain's lower layer exists on the remote: git push (or git push -u origin <branch> if never pushed).

2. Create the layer off the current branch

git checkout -b feature/<feature-suffix>-stack-<desc>

• Branch from the current feature branch, never from main; the layer must sit on top of the work below it.
• <feature-suffix> is the feature branch name without its feature/ prefix; <desc> is a short kebab-case description. Example: on feature/csv-connector, an encoding bug becomes feature/csv-connector-stack-fix-encoding.
• Alternatively gh stack add feature/<feature-suffix>-stack-<desc> creates and tracks the branch in one step if the stack is already initialised.

3. Implement the layer to full standard

Being unplanned lowers no bars. All CLAUDE.md rules apply:

• TDD (failing test first; for a bug the test must reproduce it before the fix).
• Build/test gates: targeted during the loop, dotnet build JIM.sln and dotnet test JIM.sln clean before the PR (or the documented non-code exceptions).
• Changelog entry under [Unreleased] plus public docs if the change is user-facing.
• Commit with a clear message and push: git push -u origin feature/<feature-suffix>-stack-<desc>.

4. Open the layer's PR and link the stack

Follow /pr-merge conventions (title under 70 chars, JIM body template), with the base set to the branch below, NOT main:

gh pr create --base feature/<feature> --title "fix: <desc>" --body "..."

• GitHub recognises aligned chains (each PR's base is the head of the PR below) and shows a banner offering to link them into a stack; accept it. With the gh stack CLI, gh stack submit pushes the layers and creates linked PRs in one step.
• Reviewers see only this layer's diff. CI and all of main's branch protections run for every PR in the stack.
• Do NOT queue --auto: auto-merge is unsupported for stacked PRs. Landing is handled by /pr-merge when the objective is complete.

5. Continue work in the right layer

Code may only depend on its own layer or a lower one:

• Remaining feature work needs this layer's code → continue in a new layer on top: gh stack add (or branch off this layer), and repeat this pattern.

• Remaining feature work is independent of this layer → git checkout feature/<feature> and continue below. Anything that moves a lower layer (new commits, or merging origin/main into the bottom layer) leaves the layers above pointing at the old commit, so restack each of them onto its new base before merging:

  # <old-base> is the commit the layer branched from, before the branch below moved.
  # Read it off the layer's reflog, or note it before moving the lower branch.
  git -c rebase.backend=apply rebase --onto feature/<branch-below> <old-base> feature/<layer>
  git push --force-with-lease
  

  Do not use gh stack rebase here. It rebases every branch in the chain, starting with the bottom layer onto main, which is exactly the per-commit conflict replay that CLAUDE.md's merge-don't-rebase rule exists to avoid; on a long-lived bottom layer it is a large, avoidable mess (stack #1211: conflicts in three files while replaying 53 commits, aborted with gh stack rebase --abort). Only the layer whose base actually moved needs rebasing. -c rebase.backend=apply sidesteps the merge backend's misleading "local changes would be overwritten by merge" on a clean tree.

  Note that a merge commit on the bottom layer is fine and does not break the stack: linearity is required between layers, not between the bottom layer and main. Bring the bottom layer up to date with git merge origin/main, per CLAUDE.md → "Bringing a feature branch up to date with main".

6. Landing

Use /pr-merge; its "Stacked PRs" section covers the differences (rebase to stay current, no auto-merge, bottom-up atomic merge, merging from the top when the objective is done, cleanup of layer branches).

Notes and edge cases

• Stacks require all branches in the same repository and fully linear history between layers; within a stack, rebase (cascading) replaces the usual merge-don't-rebase rule.
• Keep layers shallow and single-concern; a discovery inside a layer gets its own layer the same way.
• Layer branches belong to the same session and objective as the feature branch; the -stack- naming keeps the lineage visible across parallel sessions.
• The discovery is NOT needed to deliver the objective → this skill does not apply. File an issue with native blocked-by/sub-issue links per CLAUDE.md and stay on the feature.

End the skill on a one-line status: layer branch name, its PR number and base, and which layer work is continuing in.