/stacked-prs

name: stacked-prs
description: 'Manages dependent branch stacks and stacked pull requests using safe Git topology rules. Triggers on: "create stacked PRs", "publish this stack", "sync my PR stack", "rebase this stack", "merge the stack", "retarget child PRs", "split this branch into stacked PRs", "validate this stack", "cleanup stacked branches". Use when local branches or one source branch need to become a dependency-ordered PR stack with correct parent bases, validation, synchronization, merge order, and cleanup.'
metadata:
  version: 0.1.0
  category: development
  tags: [git, pull-requests, stacked-prs, workflow]
  difficulty: advanced
  phase: ship

Stacked PRs

Build, publish, synchronize, validate, merge, and clean up stacked pull requests without corrupting branch topology.

The package identity is provider-neutral. Git is the source of truth for branch ancestry; provider PR metadata is the source of truth for review bases. GitHub through `gh` is the first documented provider adapter.

Reference Files

| File | Contents | Load When | | --- | --- | --- | | `references/stack-model.md` | Stack inference, explicit ordering, and `.stack-prs.yaml` rules | Inspecting, publishing, validating, or cleaning a stack | | `references/provider-adapters.md` | Provider adapter contract and GitHub `gh` commands | Creating, retargeting, checking, merging, or deleting PRs | | `references/sync-algorithm.md` | Rebase and force-with-lease synchronization workflow | Syncing a stack after a parent or base moves | | `references/merge-discipline.md` | Bottom-up merge and branch cleanup rules | Merging or closing out a stack | | `references/metadata-format.md` | Optional metadata schema and validation rules | `.stack-prs.yaml` exists or inference is ambiguous | | `references/provenance.md` | Commit-trailer stack identity, stamping, verification, merge-mode coupling | Creating, splitting, syncing, or merging any stack |

When To Use

| Use this skill | Use another package | | --- | --- | | Multiple dependent branches need PRs against parent branches | `ship-workflow` for one independent release PR | | A feature branch must be split into reviewable dependent branches | `task-decomposer` for planning tasks before code exists | | An existing stack needs rebasing, retargeting, validation, or merge sequencing | `pr-review` for reviewing one PR diff | | A stack must be cleaned after merge | General Git commands for unrelated branch cleanup |

Core Rules

• Run `git rev-parse --show-toplevel` before any workflow.
• Run `git status --porcelain` before rebases, pushes, PR creation, PR retargeting, merge, or cleanup.
• Stop on a dirty worktree unless the user explicitly scopes the operation to inspection only.
• Prefer existing PR `baseRefName` values over inferred ancestry.
• Use explicit branch order or `.stack-prs.yaml` when parent inference is ambiguous.
• Never use plain `git push --force`; use `git push --force-with-lease origin <branch>`.
• Merge from root to leaf. Never merge a child before its parent.
• Do not delete unmerged stack branches without explicit user instruction.
• Stamp `Stack-Id` and `Stack-Position` trailers on every commit the skill creates or splits; copy the ID from `.stack-prs.yaml` or mint it once when absent.
• Verify trailers are present and consistent before merge.
• Detect the provider merge mode before merging. Under squash-only repos, fold trailers into the squash body or stack identity is lost.

Workflow

1. Inspect

Build a stack model without modifying anything:

git rev-parse --show-toplevel
git status --porcelain
git branch --show-current
git for-each-ref --format='%(refname:short)' refs/heads
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
gh pr list --state open --json number,title,headRefName,baseRefName,state,url

Produce a table with one row per stack branch:

| Order | Branch | Parent | PR | State | Checks | | ---: | --- | --- | --- | --- | --- | | 1 | `feat/parser-core` | `main` | `#101` | open | pending | | 2 | `feat/parser-cache` | `feat/parser-core` | `#102` | open | pending |

Stop when no provider adapter is available, no local branches match the requested stack, or parent order cannot be inferred from PR bases, explicit order, or metadata.

2. Publish

Create missing PRs and retarget wrong bases:

git status --porcelain
git push -u origin <branch>
gh pr create \
  --base <parent-branch> \
  --head <branch> \
  --title "<title>" \
  --body-file <generated-body-file>
gh pr edit <number> --base <parent-branch>

Generated PR bodies must include the stack order and validation state:

## Stack

Stack-Id: `auth-refactor-a1b2c3`
Base: `main`
Position: 1/3

1. `feat/parser-core` -> this PR
2. `feat/parser-cache` -> #102
3. `feat/parser-cli` -> #103

Depends on: (none - root)
Upstack: #102

## Validation

- Pending: commands not run yet

For non-root PRs, `Depends on:` lists the parent PR number. `Upstack:` lists the immediate child PR number when known.

Stop when a branch has no commits beyond its parent, an existing PR is closed and unmerged, or the provider rejects base retargeting.

3. Sync

Rebase each stack branch onto its parent after `main` or any parent branch moves:

git status --porcelain
git fetch origin --prune
git switch <branch>
git rebase <parent-branch>
git push --force-with-lease origin <branch>

Start at the first branch above the base and continue toward the leaf. Stop on conflicts, remote lease failures, or a parent PR that closed without merge.

4. Validate

Validate the stack as reviewable slices. Run cheap checks on every branch when practical; run expensive full checks on the leaf when branch-by-branch validation is not reasonable. Record exactly what ran in each PR body.

Use the target repository's detected local gate and provider checks. Do not run armory package-evaluation commands when operating on another repository's stack.

Fo