// Create and manage stacked (dependent) pull requests for complex features
| name | stacked-prs |
| description | Create and manage stacked (dependent) pull requests for complex features |
| tags | ["git","pull-requests","branching","workflow","collaboration"] |
| related_agents | ["version-control"] |
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.
DEFAULT: Always prefer main-based PRs unless user explicitly requests stacking.
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
# 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)
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"
# 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"
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:
```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)
## 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
Option A: Sequential Merging (Recommended)
Option B: Keep Stack Until End
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)
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)
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
Before creating stacked PRs:
git-worktrees - Work on multiple PRs simultaneouslygit-workflow - General git branching patternscode-review - Review strategies for stacked PRsPython asyncio - Modern concurrent programming with async/await, event loops, tasks, coroutines, primitives, aiohttp, and FastAPI async patterns
mypy - Static type checker for Python with gradual typing, strict mode, Protocol support, and framework integration
Python data validation using type hints and runtime type checking with Pydantic v2's Rust-powered core for high-performance validation in FastAPI, Django, and configuration management.
Essential Git patterns for effective version control, eliminating redundant Git guidance per agent.
Use git worktrees for parallel development on multiple branches simultaneously
Safe patterns for evolving database schemas in production with decision trees and troubleshooting guidance.