stacked-pr-management

constellos 的头像作者 constellos

Use this skill when the user wants to "create stacked PR", "stack PRs", "dependent PR", "rebase stack", "merge stack", or manage PR dependencies. Handles stacked PR workflows for large features split across multiple dependent pull requests.

📖 中文导读:Use this skill when the user wants to "create stacked PR", "stack PRs", "dependent PR", "rebase stack", "merge stack", or manage PR dependencies. Handles stacked PR workflows for large features split across multiple dependent pull requests. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Stacked PR Management description: Use this skill when the user wants to "create stacked PR", "stack PRs", "dependent PR", "rebase stack", "merge stack", or manage PR dependencies. Handles stacked PR workflows for large features split across multiple dependent pull requests. version: 0.1.0

Stacked PR Management

Manage dependent PR workflows (stacked PRs) for large features requiring multiple review iterations.

Purpose

Stacked PR Management enables creating chains of dependent PRs where each PR builds on the previous one. Useful for large features that need incremental review or when working on multiple related changes simultaneously.

When to Use

  • Breaking large features into reviewable chunks
  • Working on dependent changes in parallel
  • Iterating on features while earlier PRs are in review
  • Maintaining clean commit history across multiple PRs

Core Capabilities

Stack Creation

# Create PR chain
BASE="main"
BRANCHES=("42-feature/base" "43-feature/middleware" "44-feature/ui")

for i in "${!BRANCHES[@]}"; do
  BRANCH="${BRANCHES[$i]}"
  NEXT_BASE=$([[ $i -eq 0 ]] && echo "$BASE" || echo "${BRANCHES[$i-1]}")

  # Create PR with base as previous branch
  PR_NUM=$(gh pr create \
    --base "$NEXT_BASE" \
    --head "$BRANCH" \
    --title "Feature part $((i+1))" \
    --body "**Stack:** Part $((i+1)) of ${#BRANCHES[@]}

$([ $i -gt 0 ] && echo "**Base PR:** Search previous PR")" \
    --json number -q .number)

  # Save to stack
  addPRToStack "$PWD" "{\"pr\": $PR_NUM, \"branch\": \"$BRANCH\", \"base\": \"$NEXT_BASE\", \"children\": []}"
done

Stack Visualization

visualizeStack "$(loadPRStack "$PWD")"
# Output:
# main
# └── #42 feat/base
#     └── #43 feat/middleware
#         └── #44 feat/ui

Stack Rebase

# When base PR merges, rebase stack
BASE_PR=42
DEPENDENTS=$(findDependentPRs "$(loadPRStack "$PWD")" $BASE_PR)

for pr in $DEPENDENTS; do
  BRANCH=$(gh pr view $pr --json headRefName -q .headRefName)
  git checkout "$BRANCH"
  git rebase main
  git push --force-with-lease
done

Utilities

  • savePRStack(cwd, stack) - Save stack state
  • loadPRStack(cwd) - Load stack state
  • addPRToStack(cwd, node) - Add PR to stack
  • removePRFromStack(cwd, prNumber) - Remove from stack
  • visualizeStack(stack) - ASCII tree visualization
  • validateStackOrder(stack) - Check for circular dependencies
  • getMergeOrder(stack) - Get bottom-up merge order
  • findDependentPRs(stack, prNumber) - Find all descendants

Examples

Create 3-PR Stack

# Feature split across 3 PRs
git checkout main
git checkout -b 1-feature/database
# ... make changes ...
git push -u origin 1-feature/database

gh pr create --base main --head 1-feature/database --title "Part 1: Database schema"

git checkout -b 2-feature/api 1-feature/database
# ... make changes ...
git push -u origin 2-feature/api

gh pr create --base 1-feature/database --head 2-feature/api --title "Part 2: API endpoints"

git checkout -b 3-feature/ui 2-feature/api
# ... make changes ...
git push -u origin 3-feature/ui

gh pr create --base 2-feature/api --head 3-feature/ui --title "Part 3: UI components"

Merge Stack in Order

STACK=$(loadPRStack "$PWD")
MERGE_ORDER=$(getMergeOrder "$STACK")

for pr in $MERGE_ORDER; do
  # Wait for CI
  gh pr checks $pr --watch

  # Merge
  gh pr merge $pr --squash --delete-branch

  # Update base of dependent PRs
  DEPENDENTS=$(findDependentPRs "$STACK" $pr)
  for dep in $DEPENDENTS; do
    gh pr edit $dep --base main
  done
done

Best Practices

  1. Keep PRs small and focused
  2. Update PR descriptions with stack context
  3. Merge bottom-up (base PR first)
  4. Rebase dependent PRs when base changes
  5. Use --force-with-lease, never --force
  6. Validate stack with validateStackOrder() before merge