| name | epic-merge |
| description | 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. |
| disable-model-invocation | true |
| allowed-tools | Bash(git:*), Bash(gh:*), Bash(bash:*), Read, Grep, Glob, AskUserQuestion, Skill |
Epic Merge — Stacked PR Chain Squash-Merge
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 1 backup | git fetch, 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 skips all destructive steps and outputs the plan only.
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.
epic: E ─── S_N (squash of PR N)
PR N+1: E ─ A1 ─ A2 ─ ... ─ B1 ─ B2
└── drop (in S_N) ──┘ └─ keep ─┘
After: git rebase --onto epic backup/pr-<N> PR_N+1
epic: E ─── S_N ─── B1' ─ B2'
Workflow
sequenceDiagram
participant U as User
participant E as /epic-merge
participant W as /watch-ci
participant GH as GitHub
E->>E: Phase 0 — analyze chain (linear?)
E->>GH: Phase 1 — fetch + create backup tags
Note over E,GH: Iteration 1 — direct squash (no rebase needed)
E->>U: AskUserQuestion (bundled gate)
U-->>E: Proceed / Dry-run / Abort
E->>GH: gh pr merge --squash
E->>GH: fetch updated epic
Note over E,GH: Iteration 2..N — rebase + force-push + CI + merge
loop For each remaining PR
E->>U: AskUserQuestion (bundled gate)
U-->>E: Proceed / Per-step / Dry-run / Abort
E->>E: rebase --onto epic backup/pr-<prev>
E->>E: verify manifest (subject + count)
E->>GH: push --force-with-lease
E->>GH: gh pr edit --base epic
E->>W: /watch-ci --sha <sha> --branch <head> --timeout <ci-timeout>
W-->>E: PASS / FAIL verdict
E->>GH: gh pr merge --squash
E->>GH: fetch updated epic
end
E->>E: Phase 3 — verify final epic log
Phase 0: Analyze PR Chain
gh pr view <N> --json number,headRefName,baseRefName,title,state
git log origin/<base>..origin/<head> --oneline | wc -l
Output a chain table:
| Order | PR | Head Branch | Base Branch | Unique Commits | State |
|---|
| 1 | #100 | feat/A | epic/xxx | N | OPEN |
| 2 | #101 | feat/B | feat/A | N | OPEN |
| ... | ... | ... | ... | ... | ... |
Validation gate — abort if any of:
- A PR's base is not the previous PR's head (chain not linear)
- Any PR is not OPEN
- Any PR has uncommitted local changes on its head branch
- Working tree is dirty (
git status --porcelain non-empty)
Phase 1: Pre-flight Backup
Creates safety nets. Original branch tips and PR-level commit fingerprints persist as git tags + manifest files so they survive shell session loss.
git fetch origin
for pr in <PR-numbers>; do
head_branch=$(gh pr view "$pr" --json headRefName -q .headRefName)
git tag -f "backup/pr-${pr}" "origin/${head_branch}"
done
for pr in <PR-numbers>; do
head=$(gh pr view "$pr" --json headRefName -q .headRefName)
base=$(gh pr view "$pr" --json baseRefName -q .baseRefName)
git log "origin/${base}..origin/${head}" --pretty=format:'%s' > ".epic-merge-pr-${pr}.manifest"
done
Why backup/pr-<N>: branch basenames collide (feat/foo vs fix/foo both become foo). PR numbers are globally unique within the repo.
Why subject-only manifest: rebase rewrites SHAs; commit subjects are stable across rebases (assuming no --squash/--fixup mid-rebase). Subject + count is the right invariant to verify.
Why origin refs: local branches drift; origin/* is SSOT.
Why tags: shell variables die on session interruption; tags persist in .git/refs/tags/.
Phase 2: Sequential Merge Loop (gated)
Iteration 1 (First PR) — direct squash, no rebase
gh pr merge <first-PR> --squash
git fetch origin <epic-branch>
Iteration 2..N — gate first, then rebase + force-push + CI + merge
For each subsequent PR (PR <N> with head branch <head>, previous PR was <prev>):
git switch -C "<head>" "origin/<head>"
git rebase --onto "origin/<epic>" "backup/pr-<prev>" "<head>"
git log "origin/<epic>..<head>" --pretty=format:'%s' > ".epic-merge-actual.manifest"
diff ".epic-merge-pr-<N>.manifest" ".epic-merge-actual.manifest"
git push --force-with-lease "origin" "<head>"
gh pr edit "<N>" --base "<epic>"
sha=$(git rev-parse "<head>")
gh pr merge "<N>" --squash
git fetch "origin" "<epic>"
Iteration Gate Design
Default: one bundled gate per iteration. Operator can opt into finer control with --per-step.
| Mode | Gate count per iteration | Gate moments | When to use |
|---|
| Bundled (default) | 1 | Before Step 2 (covers Steps 2-8) | Trusted chain, fast iteration |
--per-step | 3 | Before Step 3 (rebase), Step 5 (push), Step 7 (merge) | First-time use, untrusted diff, recovery from prior failure |
AskUserQuestion fields (bundled mode):
| Field | Value |
|---|
question | "Proceed with PR #<N> ('<title>')? Will rebase onto epic, force-push, wait for CI, then squash-merge." |
options | Proceed, Per-step approval, Dry-run only, Abort and rollback |
description per option | Show diff stats (+X -Y across F files), backup tag SHA, expected unique-commit count from manifest |
AskUserQuestion fields (per-step mode):
| Step | question (short) |
|---|
| Before rebase | "Run: git rebase --onto origin/<epic> backup/pr-<prev> <head> ?" |
| Before push | "Manifest verified (N commits). Force-push <head>?" |
| Before merge | "CI passed for #<N>. Squash-merge into <epic>?" |
Cut Point Reference
Each iteration uses the previous PR's backup tag as the rebase cut point:
| Iteration | PR | Branch | Cut Point (--base of rebase) |
|---|
| 2 | #101 | feat/B | backup/pr-100 |
| 3 | #102 | feat/C | backup/pr-101 |
| ... | ... | ... | ... |
Phase 3: Verification
git log origin/<epic-branch> --oneline -<N+5>
Expect N squash commits (newest first), each with PR number suffix (#NNN):
<sha> feat: ... (#103)
<sha> feat: ... (#102)
<sha> feat: ... (#101)
<sha> feat: ... (#100)
<sha> <previous epic commits>
Final report:
| Item | Value |
|---|
| Epic branch | epic/xxx |
| PRs merged | 4 (#100, #101, #102, #103) |
| Backup tags | backup/pr-100, backup/pr-101, ... (kept for safety) |
| CI status | All PASS (verdicts via /watch-ci) |
| Manifests | .epic-merge-pr-*.manifest (kept until --cleanup) |
| Gate transcripts | All AskUserQuestion answers logged in conversation |
Safety Rules
| Rule | Rationale |
|---|
--force-with-lease only | Prevents overwriting concurrent remote pushes |
Backup tags from origin/* | Remote is SSOT; local refs may be stale |
| Tags keyed by PR number | Avoids namespace collisions across branch prefixes |
| Manifest = subject + count (not SHA) | Survives SHA rewrite during rebase |
| Mismatch → STOP + restore | Backup tags enable instant rollback |
| CI must PASS before merge | Rebase can introduce conflicts; CI catches them |
| Update PR base before CI | CI must run against the correct epic diff |
| AskUserQuestion before destructive ops | Per @rules/git-workflow.md exception model |
/watch-ci for CI delegation | Reuses tested timeout/verdict logic; avoids inline gh run watch divergence |
Rollback
If any step fails or user aborts:
git status --porcelain
git switch -C "<head>" "backup/pr-<N>"
git push --force-with-lease "origin" "<head>"
Conflict Handling
If git rebase --onto encounters conflicts:
- Resolve conflicts manually
git rebase --continue — never --skip (commits must not be lost)- Re-verify manifest after resolution (subject set must match)
- If unresolvable →
git rebase --abort + restore from backup tag
Resume / Checkpoint (long chains)
For chains of 10+ PRs, mid-failure recovery without restart:
- Determine where the chain stopped:
git tag -l 'backup/pr-*' + git log origin/<epic> --oneline | grep -E '\(#[0-9]+\)'
- Re-invoke
/epic-merge <epic> <remaining-PRs> — Phase 0 will detect already-merged PRs from epic log and skip them
- Backup tags from prior session remain valid as long as the corresponding branches have not been re-pushed
Post-Merge Cleanup (--cleanup flag)
git branch -D <branch1> <branch2> ...
git tag -l 'backup/pr-*'
git tag -d backup/pr-100 backup/pr-101 ...
rm .epic-merge-pr-*.manifest
Arguments
| Argument | Description | Default |
|---|
<epic-branch> | Target epic branch name | Required |
<PR-list> | Comma-separated PR numbers | Auto-detect from chain |
--dry-run | Show plan + commands, skip all destructive ops | off |
--per-step | Three gates per iteration (rebase / push / merge) | off (single bundled gate) |
--cleanup | Delete local branches + manifests after success | off |
--keep-backup-tags | Keep backup tags even with --cleanup | off |
--ci-timeout <min> | Timeout passed to /watch-ci | 15 |
Examples
/epic-merge epic/gas-account-OK-49808
/epic-merge epic/feature-xxx --dry-run
/epic-merge epic/feature-xxx 100,101,102,103 --per-step
/epic-merge epic/feature-xxx --cleanup
Prerequisites
gh CLI authenticated (gh auth status)- Repository uses squash-merge only (GitHub repo setting)
- All PRs in the chain are OPEN and CI passing on their current base
- Working tree clean (
git status --porcelain empty)
- Backup tag namespace
backup/pr-* not already in use for unrelated purposes
Limitations
- Linear chains only (no diamond / parallel merges)
- Squash-merge repos only
- One epic branch per invocation
- CI delegation requires
/watch-ci to be available
Verification
References
| File | Purpose | When to Read |
|---|
@rules/git-workflow.md | Push/rebase exception model (this skill is one of three exceptions) | Before any destructive op |
skills/smart-rebase/SKILL.md | Single-PR squash-merge rebase pattern | Phase 2 rebase logic |
skills/merge-prep/SKILL.md | Pre-merge analysis primitives | Phase 0 chain analysis |
skills/watch-ci/SKILL.md | CI verdict polling — argument contract | Phase 2 Step 7 delegation |
skills/push-ci/SKILL.md | AskUserQuestion gate pattern for git push | Iteration Gate Design |
