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

# For each PR, get head/base branch and unique commit count
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

# Collision-safe backup tags keyed by PR number (NOT branch basename)
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

# Stable manifest per PR (subject-only — survives SHA rewrite during rebase)
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

# AskUserQuestion gate (see Iteration Gate Design below)
# On Proceed:
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>):

# Step 1: AskUserQuestion BEFORE any destructive op (see Gate Design)
#   On Proceed: continue Steps 2-8 atomically
#   On Per-step: re-prompt before push (Step 5) and merge (Step 7)
#   On Dry-run: print Steps 2-8 commands, do not execute
#   On Abort: stop, leave backup tags in place

# Step 2: Checkout fresh from remote
git switch -C "<head>" "origin/<head>"

# Step 3: Rebase — cut already-squashed commits, replay unique ones onto epic
git rebase --onto "origin/<epic>" "backup/pr-<prev>" "<head>"

# Step 4: Verify manifest (subject + count, NOT SHA)
git log "origin/<epic>..<head>" --pretty=format:'%s' > ".epic-merge-actual.manifest"
diff ".epic-merge-pr-<N>.manifest" ".epic-merge-actual.manifest"
# Mismatch → STOP, restore: git switch -C "<head>" "backup/pr-<N>"

# Step 5: Force-push (--force-with-lease, NEVER --force)
git push --force-with-lease "origin" "<head>"

# Step 6: Update PR base so CI runs against correct diff
gh pr edit "<N>" --base "<epic>"

# Step 7: Wait for CI — delegate to /watch-ci with proper args
sha=$(git rev-parse "<head>")
# Skill: /watch-ci --sha "$sha" --branch "<head>" --timeout <--ci-timeout value (default 15)>
# Re-enter loop only on PASS verdict; FAIL → STOP and restore from backup

# Step 8: Squash merge
gh pr merge "<N>" --squash

# Step 9: Refresh epic
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:

# 1. Working tree must be clean
git status --porcelain  # must be empty

# 2. Restore branch from backup tag
git switch -C "<head>" "backup/pr-<N>"
git push --force-with-lease "origin" "<head>"

# 3. If a merge already happened, manually revert via GitHub UI
#    (no scripted revert — too dangerous for stacked chain)

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)

# Remove local merged branches
git branch -D <branch1> <branch2> ...

# Inspect backup tags (kept by default)
git tag -l 'backup/pr-*'

# Remove backup tags only after confirming nothing went wrong
git tag -d backup/pr-100 backup/pr-101 ...

# Remove manifest files
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

# Auto-detect chain into epic branch (single gate per iteration)
/epic-merge epic/gas-account-OK-49808

# Dry-run to see plan first
/epic-merge epic/feature-xxx --dry-run

# Explicit PR list with finer per-step gates (first-time use)
/epic-merge epic/feature-xxx 100,101,102,103 --per-step

# Full cleanup after success
/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

[ ] Phase 0: Chain validated as linear, all PRs OPEN, working tree clean
[ ] Phase 1: Backup tags created from origin/* refs, keyed by PR number
[ ] Phase 1: Per-PR subject-only manifests written
[ ] Phase 2: AskUserQuestion answer recorded BEFORE the first destructive op of each iteration
[ ] Phase 2: every push uses --force-with-lease; no push command contains the bare --force flag (token-level check, not substring — --force-with-lease is allowed)
[ ] Phase 2: /watch-ci invoked with --sha <sha> --branch <head>; PASS verdict received before gh pr merge
[ ] Phase 2: Manifest diff exits 0 after each rebase
[ ] Phase 3: Final epic log shows N squash commits with (#NNN) suffix in expected order
[ ] No commit/push performed without an AskUserQuestion answer in the conversation transcript

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 |

Epic Merge — Stacked PR Chain Squash-Merge

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

--dry-run skips all destructive steps and outputs the plan only.

Core Concept

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

# For each PR, get head/base branch and unique commit count
gh pr view <N> --json number,headRefName,baseRefName,title,state
git log origin/<base>..origin/<head> --oneline | wc -l

Output a chain table:

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

# Collision-safe backup tags keyed by PR number (NOT branch basename)
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

# Stable manifest per PR (subject-only — survives SHA rewrite during rebase)
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

Phase 2: Sequential Merge Loop (gated)

Iteration 1 (First PR) — direct squash, no rebase

# AskUserQuestion gate (see Iteration Gate Design below)
# On Proceed:
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>):

# Step 1: AskUserQuestion BEFORE any destructive op (see Gate Design)
#   On Proceed: continue Steps 2-8 atomically
#   On Per-step: re-prompt before push (Step 5) and merge (Step 7)
#   On Dry-run: print Steps 2-8 commands, do not execute
#   On Abort: stop, leave backup tags in place

# Step 2: Checkout fresh from remote
git switch -C "<head>" "origin/<head>"

# Step 3: Rebase — cut already-squashed commits, replay unique ones onto epic
git rebase --onto "origin/<epic>" "backup/pr-<prev>" "<head>"

# Step 4: Verify manifest (subject + count, NOT SHA)
git log "origin/<epic>..<head>" --pretty=format:'%s' > ".epic-merge-actual.manifest"
diff ".epic-merge-pr-<N>.manifest" ".epic-merge-actual.manifest"
# Mismatch → STOP, restore: git switch -C "<head>" "backup/pr-<N>"

# Step 5: Force-push (--force-with-lease, NEVER --force)
git push --force-with-lease "origin" "<head>"

# Step 6: Update PR base so CI runs against correct diff
gh pr edit "<N>" --base "<epic>"

# Step 7: Wait for CI — delegate to /watch-ci with proper args
sha=$(git rev-parse "<head>")
# Skill: /watch-ci --sha "$sha" --branch "<head>" --timeout <--ci-timeout value (default 15)>
# Re-enter loop only on PASS verdict; FAIL → STOP and restore from backup

# Step 8: Squash merge
gh pr merge "<N>" --squash

# Step 9: Refresh epic
git fetch "origin" "<epic>"

Iteration Gate Design

Default: one bundled gate per iteration. Operator can opt into finer control with --per-step.

AskUserQuestion fields (bundled mode):

AskUserQuestion fields (per-step mode):

Cut Point Reference

Each iteration uses the previous PR's backup tag as the rebase cut point:

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:

Safety Rules

Rollback

If any step fails or user aborts:

# 1. Working tree must be clean
git status --porcelain  # must be empty

# 2. Restore branch from backup tag
git switch -C "<head>" "backup/pr-<N>"
git push --force-with-lease "origin" "<head>"

# 3. If a merge already happened, manually revert via GitHub UI
#    (no scripted revert — too dangerous for stacked chain)

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)

# Remove local merged branches
git branch -D <branch1> <branch2> ...

# Inspect backup tags (kept by default)
git tag -l 'backup/pr-*'

# Remove backup tags only after confirming nothing went wrong
git tag -d backup/pr-100 backup/pr-101 ...

# Remove manifest files
rm .epic-merge-pr-*.manifest

Arguments

Examples

# Auto-detect chain into epic branch (single gate per iteration)
/epic-merge epic/gas-account-OK-49808

# Dry-run to see plan first
/epic-merge epic/feature-xxx --dry-run

# Explicit PR list with finer per-step gates (first-time use)
/epic-merge epic/feature-xxx 100,101,102,103 --per-step

# Full cleanup after success
/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

[ ] Phase 0: Chain validated as linear, all PRs OPEN, working tree clean
[ ] Phase 1: Backup tags created from origin/* refs, keyed by PR number
[ ] Phase 1: Per-PR subject-only manifests written
[ ] Phase 2: AskUserQuestion answer recorded BEFORE the first destructive op of each iteration
[ ] Phase 2: every push uses --force-with-lease; no push command contains the bare --force flag (token-level check, not substring — --force-with-lease is allowed)
[ ] Phase 2: /watch-ci invoked with --sha <sha> --branch <head>; PASS verdict received before gh pr merge
[ ] Phase 2: Manifest diff exits 0 after each rebase
[ ] Phase 3: Final epic log shows N squash commits with (#NNN) suffix in expected order
[ ] No commit/push performed without an AskUserQuestion answer in the conversation transcript

Adoption

sd0xdev/epic-merge

$ install --global

Security Scan Results

SKILL.md

Epic Merge — Stacked PR Chain Squash-Merge

When NOT to Use

Permissions

Core Concept

Workflow

Phase 0: Analyze PR Chain

Phase 1: Pre-flight Backup

Phase 2: Sequential Merge Loop (gated)

Iteration 1 (First PR) — direct squash, no rebase

Iteration 2..N — gate first, then rebase + force-push + CI + merge

Iteration Gate Design

Cut Point Reference

Phase 3: Verification

Safety Rules

Rollback

Conflict Handling

Resume / Checkpoint (long chains)

Post-Merge Cleanup (--cleanup flag)

Arguments

Examples

Prerequisites

Limitations

Verification

References

Related Skills

sd0xdev/zh-tw

sd0xdev/watch-ci

sd0xdev/verify

sd0xdev/update-docs

sd0xdev/epic-merge

$ install --global

Security Scan Results

SKILL.md

Epic Merge — Stacked PR Chain Squash-Merge

When NOT to Use

Permissions

Core Concept

Workflow

Phase 0: Analyze PR Chain

Phase 1: Pre-flight Backup

Phase 2: Sequential Merge Loop (gated)

Iteration 1 (First PR) — direct squash, no rebase

Iteration 2..N — gate first, then rebase + force-push + CI + merge

Iteration Gate Design

Cut Point Reference

Phase 3: Verification

Safety Rules

Rollback

Conflict Handling

Resume / Checkpoint (long chains)

Post-Merge Cleanup (--cleanup flag)

Arguments

Examples

Prerequisites

Limitations

Verification

References

Related Skills

sd0xdev/zh-tw

sd0xdev/watch-ci

sd0xdev/verify

sd0xdev/update-docs