sd0xdev/sd0x-dev-flow/epic-merge
Claude Code and agent skill by sd0xdev/sd0x-dev-flow
- community
Checking that the SKILL.md file is still in the repository.
Sequential squash-merge of stacked PR chains into an epic branch. Handles dependency-ordered rebase, collision-safe backup tags, CI monitoring (delegates to /watch-ci), and post-merge verification. Use when: merging a chain of stacked PRs into an epic branch, collapsing a linear PR stack into per-PR squash commits, preparing an epic branch for final review. Triggers on: 'merge PRs into epic', 'squash chain', 'collapse PR stack', 'epic merge', or when user has a linear PR dependency chain (PR A -> B -> C) targeting an epic branch. Not for: single PR merge (use /create-pr + GitHub UI), simple rebase (use /smart-rebase), pre-merge analysis (use /merge-prep). Output: chain analysis table + backup tag manifest + per-iteration AskUserQuestion gate + verification log.
Install
npx vskill@latest install sd0xdev/sd0x-dev-flow/epic-mergeSKILL.md
The same SKILL.md was published earlier as sd0xdev/sd0x-dev-flow/epic-merge.
Epic Merge — Stacked PR Chain Squash-Merge
Read first: @skills/push-ci/references/authorization-contract.md before any push or merge — § Push safety for the credential, the unshared attestation and the force-with-lease rules, § Efficacy Boundary for what the per-iteration approval authorizes. If that Read fails, stop and report it; push and merge nothing.
Sequentially squash-merge a chain of stacked PRs into an epic branch, producing one squash commit per PR for clean per-PR review on the epic. Every destructive iteration is gated by AskUserQuestion to keep the operator in control.
When NOT to Use
- Single PR merge — use
/create-pr+ GitHub UI - Simple rebase without stacked dependencies — use
/smart-rebase - Pre-merge conflict / impact analysis only — use
/merge-prep - Diamond / parallel merge chains — this skill handles linear chains only
- Repos that use merge-commit or rebase-merge — this skill assumes squash-merge only
Permissions
This skill is one of the explicit exceptions in @rules/git-workflow.md allowed to execute git rebase --onto, git push --force-with-lease, and gh pr merge --squash. Every destructive step is gated by AskUserQuestion.
| Phase | Operation | Mutates | Approval | |
|---|---|---|---|---|
| Phase 0 step 0 refresh | bounded git fetch (§ Phase 0 step 0) | refs/remotes/origin/* + .git/FETCH_HEAD | No (local, bounded, recoverable) | |
| Phase 1 backup | git tag -f | local refs only | No (no remote / non-recoverable mutation) | |
| Phase 2 iteration | rebase + force-push + gh pr merge | local + remote | Yes — single bundled gate per iteration (or per-step with --per-step) | |
| Phase 3 verify | git log | none | No (read-only) |
`--dry-run` outputs the plan and performs exactly one bounded local *operation — enumerated rather than implied, because every earlier phrasing was a promise the flag did not keep. "Skips all destructive steps" let Phase 1 run unconditionally, so a dry run force-updated every `backup/pr- tag and left a manifest per PR in the working tree. The repair overcorrected: it said the run "writes nothing" while still running git fetch origin, which is not a read and is not confined to origin/*` — see § Phase 0 step 0. And "one bounded write" was still too strong: a refspec bounds which refs a fetch may update, not what else fetching does.
Under --dry-run | Behaviour | |
|---|---|---|
| Phase 0 step 0 refresh | Runs. The one mutating operation a dry run keeps: the bounded fetch of § Phase 0 step 0, whose ref updates are bounded to refs/remotes/origin/* plus .git/FETCH_HEAD — its other writes are not, see § --dry-run residue below. Skipping it would print a plan derived from stale refs, and a wrong plan is worse than a refreshed origin/* | |
| Phase 0 analysis | Runs — read-only, over the refs step 0 has just refreshed | |
Phase 1 git tag -f "backup/pr-*" | Skipped. Printed as a command, not executed | |
| Phase 1 manifest files | Skipped. The git log runs, but its output goes to the report instead of $(git rev-parse --git-path epic-merge)/expected-pr-*.manifest, so no file is created and none of a previous run's are overwritten | |
| Phase 2 iteration | Skipped entirely — no gate is asked, no rebase, no push, no merge. The commands are printed | |
| Phase 3 verification | Skipped — there is nothing to verify |
The residue, stated because a dry run that leaves a trace should say where. Refs: refs/remotes/origin/* and .git/FETCH_HEAD — that set is what the explicit refspec bounds. Objects and metadata: a fetch that finds new commits downloads them into the object database, and depending on configuration git may run auto-maintenance or rewrite the commit-graph on its way out; in a shallow clone it may update the shallow metadata too. None of that is destructive and none of it is bounded by a refspec, which is why the promise above is "one bounded operation" and not "one bounded write". Pass --no-auto-maintenance --no-write-commit-graph to suppress the maintenance half; the downloaded objects are inherent to fetching and remain. Nothing changes on the remote.
Core Concept
After squash-merging PR N, the original commits are replaced by a single squash commit on epic. PR N+1 still contains N's original commits as its base — these must be cut via git rebase --onto before merging N+1. The cut point is the original tip of PR N's branch, captured in Phase 1 as a backup tag.
Names in commands
A PR head branch name is not display text. It arrives from GitHub, and git check-ref-format accepts far more than the names people type: measured, refs/heads/feat/x$(printf${IFS}PWNED>&2) and refs/heads/--all both pass, git update-ref creates both, and git clone carries both to every copy of the repository. git switch -C refuses to create such a name, which is why they look impossible — creation is not how they arrive.
Two separate readers, and each needs its own answer:
| Reader | What a hostile name does | The answer | |
|---|---|---|---|
| The shell | A name pasted into a command as literal text is evaluated: case "feat/x$(printf${IFS}PWNED>&2)" in runs printf before the guard decides anything, and the guard then passes the branch as unprotected | Bind once to a variable (head=<quoted head>), then use "$head". Expanding a variable does not re-scan for $( ) — measured both ways | |
| git's option parser | Quotes are consumed by the shell, so git still sees --all as a flag. Measured: pushing such a branch without a separator answers Everything up-to-date — git took the flag and pushed every branch, none of them the one the operator approved | The separator, before the ref operand |
Every <…> slot bound above is written <quoted …>: substitute a shell-quoted value, single-quoted with each ' rendered as '\''.
And the separator ends option parsing, not refspec parsing — a third reader with its own answer. After --, git reads the operand as a refspec, where a leading + means "force" and a : splits source from destination. git check-ref-format refs/heads/+main exits 0, so +main is a legal branch name that the protected-head guards below compare against main and pass as unprotected. Measured, with a local main rewound behind the remote:
It is not only a bypass, it is the wrong branch: with a real +main branch present, that form pushed main and never created refs/heads/+main on the remote, while refs/heads/+main:refs/heads/+main created it correctly and left main untouched. So both pushes below name a full `src:dst` refspec, whose first character cannot be read as +. Write ${head} in braces — $head:refs is a modifier expansion in zsh and silently eats the :refs.
Bind at the first use, not at the first destructive one. Phase 0 reads the names and already puts them on a command line, so a binding that started at Phase 2 would leave the whole analysis step evaluating them. Every fenced block below that names a ref binds it at the top of that block — each fence is its own shell, so nothing carries over between them.
Which separator a command takes is measured, not assumed — and for one command neither works. Measured on git 2.55.0:
Subcommand names below are written without the git prefix, so that naming a command in this table is not mistaken for issuing it:
| Subcommand | Separator | Measured | |
|---|---|---|---|
push, fetch, merge-base | -- and --end-of-options | Both accepted, equivalent. -- here is a convention, not a correctness requirement | |
branch -D | -- | git branch -D -- --all deletes the branch actually named --all; without the separator git answers fatal: branch name required | |
| `rev-parse` | neither | git rev-parse -- main prints -- and main back verbatim; git rev-parse --end-of-options main prints --end-of-options and then the SHA — two lines. Either way the captured value is not a SHA, and Step 7 would hand it to /watch-ci |
rev-parse is therefore solved by `--verify --quiet` with a fully-qualified ref, never by a separator — Step 7 below uses that form.
The `+` refspec hazard above applies to `git fetch` too, and it is why the epic refresh in Steps 9 and the Iteration-1 tail names a full src:dst refspec rather than "$epic": measured, git fetch origin -- '+main' reads the + as the force modifier and fetches `main`, so an epic literally named +main would leave origin/+main stale and every later rebase would cut against the wrong tip.
A rev range takes -- too, and for a different reason than the option one. It cannot begin with -, so binding does settle the option question — but not the revision-versus-path one. When the range names a ref that does not resolve, git falls back to reading the whole argument as a pathspec, and if a matching path happens to exist the command succeeds:
Measured — and the same fallback catches a single unresolvable ref, not just a range: git log --oneline "origin/gone" answers about a path and exits 0 where … -- fatals bad revision. A wrong answer with a zero exit is worse than an error here: the manifests below are built from these arguments and then compared, so an unreadable one degrades into a mismatch that reads as "the rebase went wrong". Every revision argument in this document — range or single ref — carries the separator.
What this section does not close: git switch -C "$head" "refs/remotes/origin/$head". No separator form applies — git refuses an option-shaped branch name outright there, so such a head ends the run with git's own error and no explanation from this skill. That is a failure, not an exploit, and it is not a handled case either. Tracked in docs/features/ref-name-hardening/requests/2026-08-20-ref-name-hardening-r1.md, which owns this defect class across the ref-handling skills.
Until that redesign lands, the Phase 0 validation gate below detects it rather than letting it surface mid-run: abort if any PR head begins with -. That is not the redesign — it neither fully-qualifies nor escapes anything — it only moves an opaque failure to the point before backup tags and per-iteration approvals are created, where it costs nothing to recover from. A head beginning with - is legal to git (git check-ref-format refs/heads/-x exits 0) but unusable here, so refusing it loses no working case.
Workflow
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/epic-merge/SKILL.md
Popularity
- Repository stars
- 188
- Repository forks
- 24
- 7-day trend score
- 26
Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 21 May 2026, 6 months ago.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/sd0xdev/sd0x-dev-flow/epic-merge)