From superpowers-beads
Use when backporting or forward-porting commits between long-lived branches (release, LTS, maintenance branches) - enforces scope analysis, correct ordering, target-context verification, and audit tracking before the picked code merges
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-beads:cherry-picking-across-branchesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`git cherry-pick` succeeds whenever the patch applies. Apply-clean is not the same as correct. Long-lived branches (release, LTS, maintenance) have diverged enough from the source branch that a clean apply can still ship broken behavior.
git cherry-pick succeeds whenever the patch applies. Apply-clean is not the same as correct. Long-lived branches (release, LTS, maintenance) have diverged enough from the source branch that a clean apply can still ship broken behavior.
Core principle: scope the chain, pick in order, verify in the target's context, then propose the result through review — never push directly.
Announce at start: "I'm using the cherry-picking-across-branches skill to plan and verify this backport."
Trigger on:
Do not trigger on:
Ask or verify which branches are involved and which is protected. If either branch is a short-lived feature branch, stop and use a normal merge or rebase instead. Long-lived means: release branches, LTS branches, maintenance branches, or main when picking back from a release line.
Claim a bead for the work before touching code:
bd create --type=task --title="Backport <summary> to <target-branch>" --description="<source SHA(s), reason, target>"
bd update <issue-id> --claim
A single SHA is rarely the whole change. Before picking:
git log --oneline <source-branch> -- <paths-touched-by-fix>
git log --all --grep="<key term from the fix>"
git log --oneline <sha>^..<source-branch> -- <paths>
For each candidate, decide whether it is part of the same logical change:
fixup!, squash!, "address review", "fix typo in ").Record the picked set on the bead before running any cherry-pick:
bd comment <issue-id> "Pick set (in order): <sha1> <subject>; <sha2> <subject>; ..."
If a dependency is too large to bring along, stop and discuss the alternatives (rewrite for the target branch, partial port, or decline) instead of force-fitting a partial pick.
Cherry-pick chronologically as the commits appear on the source branch, oldest first. Out-of-order picks generate avoidable conflicts.
Branch off the target so the pick can be reviewed:
git fetch origin
git switch -c backport/<short-slug> origin/<target-branch>
Pick a range or list:
git cherry-pick -x <oldest-sha>^..<newest-sha>
# or for non-contiguous picks:
git cherry-pick -x <sha1> <sha2> <sha3>
Always pass -x so the original SHA is recorded in the commit message. This is the audit trail.
For a merge commit, pick with -m 1 (or the correct parent number) only if the merge truly represents the change you want, and document the choice in the commit message:
git cherry-pick -x -m 1 <merge-sha>
If you cannot tell which parent to use, prefer picking the underlying commits individually instead of the merge.
A clean apply does not prove correctness. A conflicting apply does not mean "pick the source side."
When conflicts appear:
After conflict resolution, run:
git diff <target-branch>...HEAD -- <paths>
Read it as a reviewer would, with no memory of the source branch.
Apply-clean is not enough. Run, in the target worktree:
<build command>
<unit test command>
<integration tests covering the changed area>
If the source branch added tests, those tests must run and pass on the target branch — not just compile. If they cannot run on the target (different framework version, missing dependency), bring the necessary plumbing as part of the pick set or stop.
Record the verification result on the bead:
bd comment <issue-id> "Backport verification on <target-branch>: <commands> -> <pass/fail>; picked SHAs: <list>."
Long-lived branches are typically protected. Open a PR even if your local merge would succeed:
git push -u origin backport/<short-slug>
gh pr create --base <target-branch> --title "Backport: <summary> (<source-shas>)" --body "..."
The PR description should include:
-x line is good but state it explicitly).Do not git push directly to the long-lived branch. Do not bypass branch protection. Do not skip review on a backport because "it already passed review on main" — the apply context is different.
For ongoing maintenance, keep an audit trail per long-lived branch so future backports can see what is already there:
-x trailer is the per-commit record.When closing the bead:
bd close <issue-id> --reason="Backported <shas> to <target-branch>; PR <url>; verified <commands>."
Single-SHA picks of multi-commit changes
"It applied cleanly, ship it"
Cherry-picking a merge commit without -m
-m <parent> and document why.Resolving conflicts by keeping source-side lines
Out-of-order picks
<oldest>^..<newest> ranges when possible.Direct push to the long-lived branch
--base <target-branch>, even for "obvious" backports.No audit trail
cherry-pick -x, record the pick set on a bead, update any project-level backport tracking.Stop and reconsider when:
-m and without a documented parent choice.Pairs with:
superpowers-beads:using-git-worktrees — do the backport in an isolated worktree off the target branch.superpowers-beads:verification-before-completion — verification before closing the bead or merging the PR.superpowers-beads:finishing-a-development-branch — for the PR/merge/cleanup decision once the backport is verified.npx claudepluginhub jbongaarts/superpowers-beads --plugin superpowers-beadsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.