Stacked pull requests

A stack is a linear chain of pull requests in one repository. The bottom targets the trunk; every layer above targets the branch below it, so each PR shows only its own concern.

main <- data-model <- api-routes <- ui
          bottom                  top

Dependencies point toward the trunk, changes to a lower layer cascade upward, and merges proceed bottom-up.

A stack map is a line in a PR body that lists the chain's PRs bottom-to-top and marks the current one. GitHub shows a native stack's order and navigation on every member PR, so a PR in a native stack carries no map; remove any map that a PR brings into one. Every other open PR in a dependent chain carries the map, because GitHub shows no chain for it.

Scope and safety

Bound the work to the requested operation. Explanations, reviews, and status checks are read-only. Creation and maintenance may change only the local branches and linked PRs needed for that operation. A later lifecycle stage must be explicitly included in the request, except follow-up: new layers continue into pr-followup Drive unless the user asked for no follow-up, using Follow up layers below. This skill keeps topology, rebases and landing.

Merging requires the user's explicit approval for the exact PR set and merge method immediately before the merge command, except the user's own PRs in a repository that pr-followup's personal-repository merge policy covers: those land bottom-up under that standing authorization once each layer passes its gates. Preserve unrelated dirty-tree work. Before rewriting ancestry, record the current branch and relevant tips so every original commit remains reachable until verification.

Under that standing authorization, enter the selected route's merge branch for the current bottom PR only. After its verified merge, repair the remaining chain through that route's maintenance branch and rebuild the next bottom's gate evidence before landing it. Outside that policy, retain the exact PR set and method the user approved.

When a request, project rule or task record sets a review-size cap, carry it through the selected route. Before pushing or creating PRs, invoke pr in Check cap mode for each layer, passing its actual immediate PR base, selected head and cap. An upper layer is never checked cumulatively against trunk. Require a current within-cap result; if pr is unavailable, report the missing check and keep capped publication pending. The selected stack route retains mutation and remediation ownership under the shared contract defined by pr. Read-only inspection may use the same check and report its verdict without publishing.

Before pushing or creating new layers' PRs, invoke pr in Review gate mode for each new layer, bottom-up, against its immediate PR base. The stack route applies the fixes and restacks the layers above before reviewing them.

Route the request

Choose one primary route, load its file, select the requested operation there, and stop when that operation's completion criterion is satisfied; after creating or extending layers, continue as Scope and safety directs. For a request that explicitly includes several operations, complete them in dependency order and satisfy each criterion before loading the next.

Decide the route in this order:

1. Stack-aware CI and integrations when the fix changes a workflow, bot, GraphQL client, or webhook because of stack state. Product-code and test failures use another route. Load references/automation.md.
2. API when REST owns the state: a bot, integration, stateless job, or explicit REST request performs a native-stack operation. Load references/api-workflow.md.
3. Otherwise run gh extension list and record the result.
   • Manual when the user explicitly asks for ordinary dependent PRs instead of a native stack. Load references/manual-chain.md.
   • CLI otherwise: github/gh-stack is installed, or it is absent and the route installs it before its first command. Only the user or a project rule can prohibit installation. Load references/cli-workflow.md.

Any other request for stacked or dependent PRs asks for a native stack. When installing the absent extension is prohibited or fails, report a blocker with that observation and offer ordinary dependent PRs or, with the user's authorization, the API route. When GitHub reports native stacks unavailable for the repository, report a blocker and offer ordinary dependent PRs. The manual route then follows only the user's choice, and a chain that gh-stack already tracks moves to it through the migration section of troubleshooting.md.

GitHub reports native stacks unavailable when a failed native-stack read, link, or submit is confirmed by the stack-list check in cli-create.md; routing does not probe for it. During a read-only request, report it and keep inspecting through Git and PR reads without changing tracking or ownership.

Existing branches and PRs that no tool tracks yet do not decide the route. On the CLI route, a mutation adopts them first as part of the requested operation, through the adopt step in cli-create.md and the adoption section of troubleshooting.md, keeping every existing tip. Branches that another tool manages follow the interoperability section there instead. Linked Git worktrees, including WorkTrunk's, are not another branch manager: gh-stack tracks their branches. Read-only requests inspect untracked branches without writing tracking.

Keep one mutation owner throughout an operation. Reading through another interface is safe, but switching writers during a mutation can desynchronize local tracking and GitHub state. Once the stack view shows that gh-stack tracks a chain, a plain git rebase or push on its branches switches the writer. When the user explicitly moves such a chain to manual, migrate ownership through troubleshooting.md first.

Routing is complete when the requested operation, the route, and the observation that decided it are recorded, such as the extension listing, a failed install, GitHub's report, the user's explicit choice, or the REST or automation context. For repository-bound work, also identify the repository, trunk, push remote, and authenticated principal. Before a mutation, record the current branch, dirty paths, relevant branch tips, and intended remote objects.

Follow up layers

Run a Drive pass for every new layer before waiting. Keep one stack mutation owner; each pass returns its head/base, result and pending watch action to that owner instead of arming a watch or ending the turn. Complete authorized repairs and bottom-up landing first, then refresh affected layers. In T3 Code, arm all remaining layer watches in one batched host invocation and yield, as pr-followup's T3 Code adapter directs. Reuse existing watches. Report any layer whose watch failed; a first layer's wait never postpones the other layers' initial passes.

Conditional references

The primary route points to these only when their branch is reached:

• references/stack-design.md — plan layers before creating branches or splitting existing work.
• references/troubleshooting.md — recover from a failure, divergence, adoption, restructuring, worktrees, or another branch manager.