use-graphite

name	use-graphite
description	Manage stacked PRs with Graphite CLI (gt) instead of git push/gh pr create. Auto-detects Graphite repos and blocks conflicting commands with helpful alternatives. Use when: (1) About to run git push or gh pr create in a Graphite repo, (2) Creating a new branch for a feature, (3) Submitting code for review, (4) Large changes that should be split into reviewable chunks, (5) Hook blocks your git command and suggests gt equivalent. NOT for: repos not initialized with Graphite, git add/commit/status/log. Triggers: git push blocked, gh pr create blocked, create branch, submit PR, stacked PRs, split large PR, gt create, gt submit, graphite workflow.
metadata	{"author":"ai-dev-atelier","version":"1.0"}

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:

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

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.