Use Graphite – Stacked PRs

Graphite enables stacked PRs – chains of dependent PRs that build on each other. Essential for large changes that would be overwhelming as single PRs.

Assess Current State First

Always run these commands to understand where you are:

bash skills/use-graphite/scripts/graphite-detect.sh   # Is Graphite active?
gt log short                                           # Current stack structure
git status                                             # Uncommitted changes?

Interpret the output:

If you have uncommitted changes:

1. Commit them first: git add . && git commit -m "..."
2. Then submit: gt submit or gt submit --stack

If unsure which branch you’re on: git branch --show-current

Quick Start

First, check if Graphite is active:

bash skills/use-graphite/scripts/graphite-detect.sh

• enabled: true → Use gt commands for branch/PR operations
• enabled: false → Use standard git/gh, this skill does not apply

Core Workflow

Single PR

# 1. Develop and test FIRST (on current branch or main)
# make changes
# verify locally (run your project's test/lint/build commands)

# 2. THEN create branch and commit verified code
gt create my-feature
git add . && git commit -m "feat: add feature"
gt submit                       # CI should pass (you verified locally)

Stacked PRs (Large Changes)

# Step 1: Develop and verify schema changes
# make schema changes, verify locally FIRST
gt create step-1-schema
git add . && git commit -m "feat(db): add schema"

# Step 2: Develop and verify API changes (on top of step-1)
# make API changes, verify locally FIRST
gt create step-2-api
git add . && git commit -m "feat(api): add endpoints"

# Step 3: Develop and verify UI changes (on top of step-2)
# make UI changes, verify locally FIRST
gt create step-3-ui
git add . && git commit -m "feat(ui): add panel"

# Submit entire stack (all layers verified)
gt submit --stack

Key pattern: Each layer follows develop → test → verify → gt create → commit. Only submit when ALL layers are verified locally.

CRITICAL: CI Must Pass

Verify BEFORE creating branches and committing.

Check your project for verification commands (look for package.json scripts, Makefile targets, Cargo.toml, pyproject.toml, CI config, or README). Run tests, type checks, linting, and build locally before submitting.

WRONG workflow (commit-and-pray):
1. gt create feature
2. Make changes
3. Commit and gt submit → CI fails
4. Fix → gt submit → CI fails again
5. Repeat 5 times...
Result: 5 failed CI runs, broken commit history

CORRECT workflow (verify-then-commit):
1. Make changes
2. Run tests/lint/build LOCALLY
3. Fix issues until green
4. gt create feature
5. Commit verified code
6. gt submit → CI passes
Result: 1 clean submission

Rule: If local tests fail, you’re not ready to commit. Fix first, verify, then create branch and commit.

When to Stack

DO: Best Practices

DON’T: Common Mistakes

Command Translation

What Graphite Does NOT Replace

Keep using these normally:

• git add, git commit – staging and committing
• git status, git log, git diff – inspection
• git stash, git checkout <branch> – switching, stashing

Updating a Stack

After review feedback on an earlier PR:

gt checkout step-1-schema
# make changes, TEST LOCALLY
git add . && git commit -m "fix: address review feedback"
gt restack                      # Update dependent branches
gt submit --stack               # Push entire stack

Resuming Work (After Context Loss)

If you’re continuing work and unsure of the state:

# 1. Check current state
gt log short                    # See full stack structure
git status                      # Any uncommitted changes?
git log --oneline -3            # Recent commits

# 2. Common scenarios:

CRITICAL: After Submit – Validate PR Description

gt submit creates PRs in draft mode with empty descriptions. You MUST fill them.

After every gt submit, immediately run:

# Get the PR number from gt submit output, then:
gh pr view <PR_NUMBER> --json body --jq '.body'

If the body is empty or just contains template placeholders:

gh pr edit <PR_NUMBER> --title "feat: meaningful title" --body-file /path/to/pr-body.md

What a complete PR description needs:

• Summary of what the PR does (2-3 sentences)
• Type of change (bug fix, feature, refactor, etc.)
• How it was tested
• Files changed overview (for larger PRs)

Never leave PRs with:

• Fixes # (issue) placeholder unfilled
• Empty checkboxes with no selections
• Template comments like <!-- What does this PR do? -->
• Just ## Summary headers with no content

Workflow reminder:

gt submit                           # Creates draft PR
gh pr view <N> --json body --jq '.body'  # Check if body is populated
# If empty/template:
gh pr edit <N> --title "..." --body "..."  # Fill it properly

Emergency Fallback

If gt commands fail (auth expired, service down), save your work:

git add .
git commit -m "wip: saving progress"
git push origin HEAD  # BYPASS_GRAPHITE: gt service unavailable

The # BYPASS_GRAPHITE: <reason> comment is required to bypass the hook.

Troubleshooting

Splitting a Large Commit

If you realize a commit should have been stacked:

git reset HEAD~1 --soft          # Undo commit, keep changes staged
gt create step-1-types
git add src/types/* && git commit -m "feat: add types"
gt create step-2-impl
git add src/api/* && git commit -m "feat: implement"
gt submit --stack

View Stack Status

gt log short

  main
  └── feat-schema (#234, approved)
      └── feat-api (#235, changes requested)
          └── feat-ui (#236, pending review)

Scripts

References

• references/graphite-workflow.md – Extended stacking examples, team patterns, CI integration

Integration

Output

Branches and PRs managed via Graphite CLI. View stack: gt log short.