Working with Graphite Stacked Workflows

Graphite Stacked Workflow Expertise

You are working in a repository that uses Graphite for stacked PRs.

Core Philosophy

Every feature is a stack of small PRs (<200 LOC each), not one large PR.

The Transformation

Traditional (❌):

"Add authentication" → One 500 LOC PR → Wait for review → 😴

Graphite (✅):

"Add authentication" → 5 PRs:
  1. Users table (~60 LOC)
  2. Auth service (~150 LOC)
  3. Login endpoints (~80 LOC)
  4. UI components (~120 LOC)
  5. Tests (~90 LOC)
→ Submit stack → Review in parallel → Merge bottom-up → 🚀

Key Principles

1. Stack-first thinking - Break work into logical pieces immediately
2. <200 LOC per PR - Keep reviewable
3. Build upstack immediately - Don't wait for approval
4. Use GT commands, not git - They understand stacks
5. Amend commits, don't append - Clean history

Critical Safety Rules

❌ NEVER use these git commands:

• git checkout -b → Use gt create -am "msg" instead
• git merge → Use gt sync -f or gt fold
• git rebase → Use gt restack or gt sync -f
• git commit --amend → Use gt modify -a
• git push --force → Use gt submit

Why: Git commands don't understand stacks. GT commands auto-restack dependents.

Full translation table: reference/git-vs-gt.md

Planning Work as Stacks

When planning, immediately structure as stacks:

Bad todo:

- Add user authentication

Good todos (each = one PR):

- Add users table (~60 LOC) - blocks auth service
- Add auth service (~150 LOC) - blocks endpoints
- Add login endpoints (~80 LOC) - blocks UI
- Add UI components (~120 LOC) - blocks tests
- Add tests (~90 LOC)

Quick Planning Framework

Choose one:

1. Functional Components - Split by layer (DB, backend, frontend, tests)
2. Iterative - MVP first, then enhancements
3. Refactor/Change - Refactor in one PR, change in next
4. Version Bumps - Mechanical changes first
5. Riskiness - Safe changes first, risky ones upstack

Deep dive: reference/planning-stacks.md - All 5 frameworks with examples, LOC estimation, planning templates

Essential Commands

Core Workflow

gt create -am "msg"      # Create branch + commit
gt modify -a             # Amend commit + auto-restack dependents
gt submit --stack        # Submit entire stack
gt sync -f               # Daily sync (every morning)
gt up / gt down          # Navigate stack
gt log                   # Visualize structure

Common Patterns

# Morning routine
gt sync -f && gt log

# Start work
gt bottom && gt create -am "First piece"

# Address feedback
gt checkout branch && gt modify -a && gt submit -u

# Submit stack
gt submit --stack

Complete reference: reference/commands.md - All flags, edge cases, advanced usage

Handling Feedback

Simple feedback:

gt checkout pr-with-feedback
# Make changes
gt modify -a              # Amend + auto-restack dependents
gt submit -u              # Update PR

Feedback on middle of stack:

# Stack: PR1 → PR2 → PR3 → PR4
# Feedback on PR2
gt checkout pr-2-branch
# Make changes
gt modify -a              # Amends PR2, restacks PR3 and PR4 automatically!
gt submit --stack -u      # Update all PRs

You don't manually rebase. GT handles it.

Complex scenarios: reference/feedback-handling.md - Conflicts, multi-commit branches, cherry-pick patterns, gt absorb

Anti-Patterns to Prevent

🚨 About to use git checkout/merge/rebase/amend? → STOP. Check reference/git-vs-gt.md for GT equivalent.

🚨 Planning one large PR? → STOP. Split into <200 LOC pieces. Use reference/planning-stacks.md.

🚨 Creating fixup commits? → STOP. Use gt modify -a to amend instead (clean history).

🚨 Mixed concerns in one branch? → STOP. Split: one branch = one concern.

When to Load Reference Docs

You already have the essentials above. Load reference docs when you need:

• reference/planning-stacks.md - Deep dive on 5 frameworks, LOC estimation, planning templates
• reference/workflow-patterns.md - Complete end-to-end workflows for features/bugs/refactors
• reference/feedback-handling.md - Complex conflicts, multi-commit branches, gt absorb
• reference/git-vs-gt.md - Complete git→gt translation table
• reference/stacking-patterns.md - Framework decision trees, real-world examples
• reference/commands.md - All gt commands with flags and edge cases
• reference/best-practices.md - Golden rules, metrics, team collaboration

Progressive disclosure: Start here. Load reference docs only when needed.

Quick Example

User: "Add user search"

Your response:

I'll implement as a Graphite stack with 5 PRs:

1. Add search index (~40 LOC) - Database index
2. Add search API (~80 LOC) - GET /api/search endpoint
3. Add SearchBar (~100 LOC) - UI component
4. Add SearchResults (~90 LOC) - Results display
5. Add tests (~100 LOC) - Integration tests

Total: ~410 LOC → 5 reviewable PRs under 150 LOC each.

Implementation:
```bash
gt bottom
gt create -am 'Add search index on users.name'
# [implement]
gt create -am 'Add GET /api/search endpoint'
# [implement]
gt create -am 'Add SearchBar component'
# [implement]
gt create -am 'Add SearchResults component'
# [implement]
gt create -am 'Add search integration tests'
# [implement]
gt submit --stack

Stack submitted! All 5 PRs ready for review.

---

**This skill makes you a Graphite expert. Apply stack-first thinking to all development work automatically.**