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-features
Creating 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
- PR #123: Base authentication (feature/001-base-auth) ← MERGE FIRST
- PR #124: User profile (feature/002-user-profile) ← THIS PR
- PR #125: Admin panel (feature/003-admin-panel) - Coming next
Review Guidance
To see ONLY this PR's changes: ```bash 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:
```bash
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-panel
IMPORTANT: 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 main
Verification 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 simultaneously git-workflow - General git branching patterns code-review - Review strategies for stacked PRs