Stacked Pull Requests
Overview
Stacked PRs are dependent pull requests where each PR builds on the previous one. Use this pattern for complex features that need logical separation and parallel review.
When to Use
✅ Use Stacked PRs When:
- User explicitly requests "stacked PRs" or "dependent PRs"
- Large feature needs to be split into logical phases
- Each phase has clear dependencies on previous phases
- User is comfortable with rebase workflows
❌ Use Main-Based PRs When (Default):
- Features are independent
- Simple bug fixes or enhancements
- Multiple agents working in parallel
- User doesn't specify preference
DEFAULT: Always prefer main-based PRs unless user explicitly requests stacking.
Branch Naming Convention
Use sequential numbering to show dependencies:
feature/001-base-authentication # PR-001 (base)
feature/002-user-profile # PR-002 (depends on 001)
feature/003-admin-panel # PR-003 (depends on 002)Alternative patterns:
auth/01-foundation
auth/02-user-flow
auth/03-admin-featuresCreating Stacked PRs
Step 1: Create Base PR (PR-001)
# Start from main
git checkout main
git pull origin main
# Create base branch
git checkout -b feature/001-base-auth
# Implement base functionality
# ... work ...
# Push and create PR
git push -u origin feature/001-base-auth
# Create PR in GitHub/GitLab
# Title: "[1/3] Base authentication foundation"
# Base: main
# Description: Include stack overview (see template below)Step 2: Create Dependent PR (PR-002)
CRITICAL: Base on previous feature branch, NOT main
# Start from PR-001's branch
git checkout feature/001-base-auth
git pull origin feature/001-base-auth
# Create dependent branch
git checkout -b feature/002-user-profile
# Implement dependent functionality
# ... work ...
# Push and create PR
git push -u origin feature/002-user-profile
# Create PR in GitHub/GitLab
# Title: "[2/3] User profile management"
# Base: feature/001-base-auth ← NOT main!
# Description: "Depends on PR #123"Step 3: Create Final PR (PR-003)
# Start from PR-002's branch
git checkout feature/002-user-profile
git pull origin feature/002-user-profile
# Create final branch
git checkout -b feature/003-admin-panel
# Implement final functionality
# ... work ...
# Push and create PR
git push -u origin feature/003-admin-panel
# Create PR in GitHub/GitLab
# Title: "[3/3] Admin panel with full auth"
# Base: feature/002-user-profile ← NOT main!
# Description: "Depends on PR #124"PR Description Template
Use this template for stacked PRs:
## This PR
[Brief description of changes in THIS PR only]
## Depends On
- PR #123 (feature/001-base-auth) - Must merge first
- Builds on top of authentication foundation
## Stack Overview
1. PR #123: Base authentication (feature/001-base-auth) ← MERGE FIRST
2. PR #124: User profile (feature/002-user-profile) ← THIS PR
3. PR #125: Admin panel (feature/003-admin-panel) - Coming next
## Review Guidance
To see ONLY this PR's changes:git diff feature/001-base-auth...feature/002-user-profile
Or on GitHub: Compare `feature/002-user-profile...feature/001-base-auth` (three dots)
## Testing
- Tested in combination with PR #123
- Includes tests for user profile functionality
- Integration tests pass with base auth layer
Managing Rebase Chains
When Base PR Changes (Review Feedback)
If PR-001 gets updated, rebase dependent PRs:
# Update PR-001 (base)
git checkout feature/001-base-auth
git pull origin feature/001-base-auth
# Rebase PR-002 on updated base
git checkout feature/002-user-profile
git rebase feature/001-base-auth
git push --force-with-lease origin feature/002-user-profile
# Rebase PR-003 on updated PR-002
git checkout feature/003-admin-panel
git rebase feature/002-user-profile
git push --force-with-lease origin feature/003-admin-panelIMPORTANT: Use --force-with-lease not --force for safety
Merge Strategy
Option A: Sequential Merging (Recommended)
- Merge PR-001 to main
- Change PR-002's base to main (GitHub: "Edit" button on PR)
- Merge PR-002 to main
- Change PR-003's base to main
- Merge PR-003 to main
Option B: Keep Stack Until End
- Merge PR-001 to main
- Keep PR-002 based on feature/001 until PR-001 fully merged
- Then rebase PR-002 onto main
- Repeat for PR-003
Common Pitfalls
❌ WRONG: All PRs from main
git checkout main
git checkout -b feature/001-base
# PR: feature/001-base → main
git checkout main # ← WRONG
git checkout -b feature/002-next
# PR: feature/002-next → main # ← WRONG (independent, not stacked)✅ CORRECT: Each PR from previous
git checkout main
git checkout -b feature/001-base
# PR: feature/001-base → main
git checkout feature/001-base # ← CORRECT
git checkout -b feature/002-next
# PR: feature/002-next → feature/001-base # ← CORRECT (stacked)Agent Instructions
When delegating stacked PR creation to version-control agent:
Task: Create stacked PR branch structure
Stack Sequence:
1. PR-001: feature/001-base-auth → main (base layer)
2. PR-002: feature/002-user-profile → feature/001-base-auth (depends on 001)
3. PR-003: feature/003-admin-panel → feature/002-user-profile (depends on 002)
Requirements:
- Each branch MUST be based on previous feature branch
- Use sequential numbering (001, 002, 003)
- Include "depends on" notes in commit messages
- Create PR description with stack overview
CRITICAL: PR-002 bases on feature/001-base-auth, NOT on main
CRITICAL: PR-003 bases on feature/002-user-profile, NOT on mainVerification Checklist
Before creating stacked PRs:
- User explicitly requested stacked PRs
- Feature has clear logical phases
- Each phase has dependency on previous
- User understands rebase workflow
- Branch names use sequential numbering
- Each branch created from correct base (previous feature branch)
- PR descriptions include dependency information
- Stack overview documented in each PR
Related Skills
git-worktrees- Work on multiple PRs simultaneouslygit-workflow- General git branching patternscode-review- Review strategies for stacked PRs