understanding-cross-phase-stacking

Understanding Cross-Phase Stacking

Overview

Phases automatically build on each other's completed work. Understanding how phases chain together is essential for correct execution.

This is a reference skill - read it to understand cross-phase dependencies, not to execute a workflow.

When to Use

Use this skill when:

• Starting a new phase (need to understand what base to build from)
• Debugging stack relationships across phase boundaries
• Verifying phases are chaining correctly
• Understanding why parallel worktrees use specific base branches

Mental model check: If you're thinking "create worktrees from {runid}-main branch", you need this skill.

The Cross-Phase Inheritance Principle

MAIN WORKTREE CURRENT BRANCH = LATEST COMPLETED WORK

Key insight:

• Sequential phases leave main worktree on their last task's branch
• Parallel phases leave main worktree on their last stacked branch
• Next phase (sequential or parallel) inherits from current branch, not original base

This creates automatic linear chaining across all phases.

Example: Sequential → Parallel → Sequential

Phase 1 (Sequential) - Database Setup

# Working in: .worktrees/{runid}-main
# Starting from: {runid}-main (base branch)

# Task 1: Database schema
gs branch create {runid}-task-1-1-database-schema
# Creates branch, commits work
# Main worktree now on: {runid}-task-1-1-database-schema ← KEY STATE

Phase 1 result:

• Branch created: {runid}-task-1-1-database-schema
• Main worktree current branch: {runid}-task-1-1-database-schema
• This branch becomes Phase 2's base

Phase 2 (Parallel) - Three Feature Implementations

# Base detection (CRITICAL):
BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
# Returns: {runid}-task-1-1-database-schema ← Inherits from Phase 1

# Create parallel worktrees FROM Phase 1's completed branch
git worktree add .worktrees/{runid}-task-2-1 --detach "$BASE_BRANCH"
git worktree add .worktrees/{runid}-task-2-2 --detach "$BASE_BRANCH"
git worktree add .worktrees/{runid}-task-2-3 --detach "$BASE_BRANCH"

# All 3 parallel tasks build on Phase 1's database schema

After parallel tasks complete and stack:

# In main worktree (.worktrees/{runid}-main):
# Branch 1: {runid}-task-2-1-user-service → tracked
# Branch 2: {runid}-task-2-2-product-service → tracked, upstacked onto Branch 1
# Branch 3: {runid}-task-2-3-order-service → tracked, upstacked onto Branch 2

# Main worktree now on: {runid}-task-2-3-order-service ← KEY STATE

Phase 2 result:

• Linear stack: database-schema → user-service → product-service → order-service
• Main worktree current branch: {runid}-task-2-3-order-service
• This branch becomes Phase 3's base

Phase 3 (Sequential) - Integration Tests

# Working in: .worktrees/{runid}-main (reused from Phase 1)
# Current branch: {runid}-task-2-3-order-service (from Phase 2)

# Task 1: Integration tests
gs branch create {runid}-task-3-1-integration-tests
# Automatically stacks on Phase 2's last task via natural stacking

Phase 3 result:

• Linear chain: Phase 1 → Phase 2 tasks → Phase 3
• Complete stack shows all work in order

Verification Between Phases

Before starting parallel phase (check inheritance):

# Verify base branch before creating worktrees
BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
echo "Starting parallel phase from: $BASE_BRANCH"
# Should show previous phase's completed branch, NOT {runid}-main

Before starting sequential phase (check current state):

# Verify starting point
CURRENT_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
echo "Starting sequential phase from: $CURRENT_BRANCH"
# Should show previous phase's last stacked branch

After phase completes (verify stack):

cd .worktrees/{runid}-main
gs log short
# Should show linear chain including all previous phases

Key Principles

1. Main worktree tracks progress

   • Current branch = latest completed work
   • Not static - changes as phases complete

2. Parallel phases inherit from current

   • Use git -C .worktrees/{runid}-main branch --show-current as base
   • NOT {runid}-main (that's the original starting point)

3. Parallel stacking preserves continuity

   • Last stacked branch becomes next phase's base
   • Checkout last branch after stacking completes

4. Sequential phases extend naturally

   • gs branch create stacks on current HEAD
   • No manual base specification needed

5. No manual intervention needed

   • Cross-phase chaining is automatic
   • Following per-phase patterns creates correct chain

Common Mistake: Creating From Wrong Base

❌ Wrong: Creating parallel worktrees from original base

# DON'T DO THIS:
git worktree add .worktrees/{runid}-task-2-1 --detach {runid}-main

Why wrong: Ignores Phase 1's completed work. Phase 2 won't have database schema from Phase 1.

Result: Broken dependency chain. Phase 2 builds on stale base instead of Phase 1's changes.

✅ Correct: Creating parallel worktrees from current branch

# DO THIS:
BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
git worktree add .worktrees/{runid}-task-2-1 --detach "$BASE_BRANCH"

Why correct: Inherits all previous work. Phase 2 builds on Phase 1's completed branch.

Result: Linear chain across all phases.

Mental Model Check

If you're thinking:

• "Create worktrees from {runid}-main" → WRONG. Use current branch.
• "Parallel tasks should start fresh" → WRONG. They inherit previous work.
• "Phase boundaries break the stack" → WRONG. Stack is continuous across phases.

Correct mental model:

• Main worktree is a moving cursor pointing to latest work
• Each phase extends the cursor position, doesn't reset it
• Stack is one continuous chain, not per-phase segments

Quick Reference

Starting parallel phase:

BASE_BRANCH=$(git -C .worktrees/{runid}-main branch --show-current)
# Use $BASE_BRANCH for all worktree creation

Starting sequential phase:

# Already on correct branch - just create next branch
gs branch create {runid}-task-{phase}-{task}-{name}
# Automatically stacks on current HEAD

Verifying cross-phase chain:

cd .worktrees/{runid}-main
gs log short
# Should show linear progression through all phases

The Bottom Line

Phases chain automatically through main worktree's current branch.

If you're manually specifying base branches or creating worktrees from {runid}-main, you're breaking the automatic inheritance system.

Trust the pattern: main worktree tracks progress, new phases build from current state.