graphite-split-stack

name

graphite-split-stack

description

Split a PR or branch into a smaller Graphite stack using a human-style `gt split` workflow. Ask the user how to split the work, optionally squash to one commit with `gt squash`, rebuild named branches with `git branch`, re-track them with `gt track`, and verify the final top branch matches the original tree exactly. Use when the user asks to split a PR, split a branch into multiple Graphite branches, preserve an existing PR on one split branch, or manually emulate `gt split`.

Graphite Split Stack

Use this skill when the user wants to turn one branch or PR into a smaller Graphite stack.

For normal day-to-day gt work, use .cursor/skills/graphite/SKILL.md.

If the work is still uncommitted in the current dirty working tree and you just need to mint new child branches above the current branch, use .cursor/skills/graphite-create-stack/SKILL.md instead.

Defaults

• Ask the user for the split plan before changing anything.
• Prefer 2-4 slices unless the user already has a specific breakdown.
• Treat the split as ordered oldest to newest.
• Assume only git and gt are available. Validation commands are repo-specific.
• Prefer keeping the original branch name on the new top branch when the current branch already has tracked children, unless the user explicitly wants something else.
• It is acceptable for an intermediate split branch to add temporary compatibility code, placeholder wiring, or a shim if that is required to keep that branch buildable and testable. That temporary code should be planned up front and removed by later split branches so the final top-branch tree still matches the original tree exactly.

Before Mutating

1. Confirm the current branch is safe to split:
   • clean worktree
   • no rebase in progress
   • editable Graphite branch, not trunk
2. Capture:
   • original branch name
   • original tracked parent branch
   • original HEAD SHA
   • original top-tree SHA
   • any tracked children
3. Ask the user to confirm:
   • the ordered slices
   • branch names
   • which slice, if any, keeps the original branch name
   • whether the original PR should be closed if no slice keeps that name
   • what validation each slice must pass
   • whether temporary placeholder code is acceptable if an earlier slice needs it to stay green
4. If the user has not specified the split, inspect the diff and propose a concrete split before proceeding.

Core Workflow

1. If needed, squash the current branch to one commit with gt squash --no-edit.
2. Detach HEAD and turn that single commit back into working-tree changes.
3. Build the split commits oldest to newest, validating each slice before moving on.
4. Introduce the smallest temporary compatibility shim or placeholder code needed to keep an intermediate branch green, and remove it in a later slice once its dependents land.
5. After each commit, create or move the corresponding branch ref with git branch or git branch -f.
6. Rebuild the Graphite parent chain with gt track <branch> --parent <parent>.
7. If the original branch had tracked children, restack or otherwise re-home them onto the new top branch before finishing.
8. Verify the final top branch tree matches the original saved tree hash exactly.

Hard Stops

• The user has not approved the split plan.
• A slice cannot pass its validation independently.
• A proposed branch name collides and the user has not approved the alternative.
• Keeping an intermediate branch green would require placeholder code or a compatibility shim that the user has not approved.
• No resulting branch keeps the original name and the user has not confirmed that the original PR should be closed.
• The final top branch tree hash differs from the original tree hash.
• Existing upstack branches need recovery and the restack plan is unclear.

Reference

Read reference.md for the split-specific preflight, branch and PR continuity rules, gt track flow, child-branch caveats, and worked examples.

For the shared discovery prompt, validation-isolation workflow, recovery rules, temporary compatibility guidance, and final verification checklist, read ../graphite-stack-shared/REFERENCE.md.