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:
gt log short shows You are Next action
main only (no branches) Not in a stack gt create <branch> to start
Branch with ← marker On that branch in stack Continue work, then gt submit
Multiple branches in tree Mid-stack Check which branch, continue or gt checkout
(merged) on parent Parent merged gt sync to update
(changes requested)
Review feedback pending Address feedback, commit, gt submit
If you have uncommitted changes:
-
Commit them first: git add . && git commit -m "..."
-
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):
- gt create feature
- Make changes
- Commit and gt submit → CI fails
- Fix → gt submit → CI fails again
- Repeat 5 times... Result: 5 failed CI runs, broken commit history
CORRECT workflow (verify-then-commit):
- Make changes
- Run tests/lint/build LOCALLY
- Fix issues until green
- gt create feature
- Commit verified code
- 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
Scenario Recommendation
Bug fix (< 100 lines) Single PR
Feature (200-500 lines) 2-3 stacked PRs
Large feature (500+ lines) Always stack
Refactor + feature Stack: refactor first
DB migration + code Stack: migration first
DO: Best Practices
Practice Why
Test before submit CI failures waste everyone's time
1 logical change per PR Easy to review, easy to revert
Stack by dependency schema → API → UI, not random splits
Keep stacks shallow (3-5 PRs) Deep stacks are hard to manage
Sync daily (gt sync ) Avoid painful merge conflicts
Use gt modify -c
Not git commit --amend in tracked branches
DON'T: Common Mistakes
Mistake Problem Fix
Submit without testing CI fails, blocks review Always run tests locally first
Split randomly PRs don't make sense alone Split by logical dependency
10-PR stacks Unmergeable, conflicts pile up Max 3-5 PRs, start new stack
Never sync Conflicts grow over time gt sync daily
Use git rebase Breaks Graphite tracking Use gt restack instead
Use git push Bypasses stack management Use gt submit
Tiny PRs for simple features Overhead without benefit Single PR for <100 lines
Command Translation
Instead of (blocked) Use (Graphite)
git checkout -b feature
gt create feature
git push
gt submit
gh pr create
gt submit
git rebase main
gt restack
git commit --amend
gt modify -c
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:
Situation What to do
Stack exists, on correct branch Continue work, commit, gt submit
Stack exists, wrong branch gt checkout <branch-name>
Changes not pushed gt submit (single) or gt submit --stack (all)
Need to add to existing stack gt create <new-branch> (adds on top of current)
Stack has merge conflicts gt sync then resolve conflicts
PRs exist but out of date gt sync && gt restack && gt submit --stack
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
Issue Solution
gt: command not found
npm install -g @withgraphite/graphite-cli
Not authenticated
gt auth login
Branch not tracked
gt track then gt submit
Stack out of sync
gt restack then gt submit --stack
Merge conflict during sync
Resolve conflicts, git add , git rebase --continue , then gt sync
Need to set up new repo gt auth login && gt repo init --trunk main
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
Script Purpose
graphite-detect.sh
Check if Graphite is active
graphite-block-hook.sh
PreToolUse hook (blocks conflicting commands)
References
- references/graphite-workflow.md
- Extended stacking examples, team patterns, CI integration
Integration
When Related Skill Action
Before submit code-quality
Run checks, ensure CI will pass
After changes git-commit
Commit with proper message
Before PR code-review
Review your changes
Output
Branches and PRs managed via Graphite CLI. View stack: gt log short .