merge-pr

merge-pr Skill

Purpose: Automate the merge pipeline for a single PR -- replacing the manual execution of /ship Phases 3.5-8. Runs lights-out: merge main, resolve conflicts, push, create PR, wait for CI, merge, and cleanup.

Relationship to /ship: Both skills are independent user-invoked entry points. /ship handles artifact validation, compound, and documentation (Phases 0-3). This skill handles the merge-through-cleanup pipeline. They do NOT invoke each other.

Arguments: Optional branch name. If omitted, auto-detects from current branch.

Phase 0: Context Detection

Detect the current environment and record the starting state for rollback. Run these commands separately and store the results:

1. Get current branch name:

git rev-parse --abbrev-ref HEAD

1. Get current commit SHA (this is the rollback point):

git rev-parse HEAD

1. Get current working directory path (worktree path):

pwd

1. Get the main repo root (first path from worktree list output):

git worktree list

Store these four values as BRANCH, STARTING_SHA, WORKTREE_PATH, and REPO_ROOT for use throughout the pipeline.

Load project conventions:

if [[ -f "CLAUDE.md" ]]; then
  cat CLAUDE.md
fi

If an argument was provided, verify that branch exists and check it out. Otherwise use the current branch.

Announce:

merge-pr: Starting pipeline for branch: <branch-name>
Starting SHA: <starting-sha> (rollback point)

Replace <branch-name> with the actual branch name and <starting-sha> with the current HEAD SHA.

Phase 1: Pre-condition Validation

Validate all pre-conditions before proceeding. On any failure, stop immediately and report.

1.1 Not on default branch

git rev-parse --abbrev-ref HEAD

If the branch is main or master, stop:

STOPPED: Cannot run merge-pr on the default branch.
Switch to a feature branch or provide a branch name as argument.

1.2 Clean working tree

git status --porcelain

If output is non-empty, stop:

STOPPED: Uncommitted changes detected. Commit changes before running merge-pr.

1.3 Compound has run

Extract the feature name from the branch (strip feat-, feature/, fix-, fix/ prefix). Search for unarchived KB artifacts matching the feature name in:

• knowledge-base/project/brainstorms/ (excluding archive/ paths)
• knowledge-base/project/plans/ (excluding archive/ paths)
• knowledge-base/project/specs/feat-<feature>/

If any unarchived artifacts are found, stop:

STOPPED: Unarchived KB artifacts found for this feature:
<list of files>

Use `skill: soleur:compound` to consolidate and archive these artifacts, then re-run `skill: soleur:merge-pr`.

If no unarchived artifacts exist (either compound already archived them, or no artifacts were created), proceed.

Phase 2: Merge Main

Fetch the latest main and merge into the feature branch:

git fetch origin main
git merge origin/main

If merge is clean (exit code 0): Proceed to Phase 4 (skip Phase 3).

If merge conflicts (exit code non-zero): Proceed to Phase 3.

Note: Version bumping is handled automatically by CI at merge time. This skill does not bump versions.

Phase 3: Conflict Resolution

Identify conflicted files:

git diff --name-only --diff-filter=U

3.1 Route conflicts

For each conflicted file, apply the appropriate resolution strategy:

| File Pattern | Strategy | |-------------|----------| | plugins/soleur/CHANGELOG.md | Merge both sides -- see 3.2 | | plugins/soleur/README.md | Accept feature branch component counts | | Generated artifacts | Take --theirs, then re-run the owning generator -- see 3.2b | | Everything else | Claude-assisted resolution -- see 3.3 |

Generated artifacts (3.2b). A generated file has no authorial intent to preserve, so 3.3 does not apply to it: hand-picking hunks produces an artifact that matches neither side's source and that no generator would emit. Resolve by discarding both sides and regenerating from the merged source. Known members and their owning generators: knowledge-base/engineering/architecture/diagrams/model.likec4.json → [regenerate-c4-model.sh](../../../../scripts/regenerate-c4-model.sh) (verify with [c4-model-freshness.test.sh](../../test/c4-model-freshness.test.sh), which is exactly the in-sync assertion), and knowledge-base/project/rule-metrics.json → [rule-metrics-aggregate.sh](../../../../scripts/rule-metrics-aggregate.sh). Lockfiles follow the same shape with a pinned toolchain — see [drain-prs/SKILL.md](../drain-prs/SKILL.md) §6(a).

For README.md (accept feature branch):

git checkout --ours plugins/soleur/README.md
git add plugins/soleur/README.md

3.2 CHANGELOG merge

CHANGELOG requires special handling to preserve entries from both sides without truncation.

Read both sides using git stage numbers (NOT git show HEAD: which only gives one side):

ours=$(mktemp -t changelog-ours.XXXXXXXX.md); theirs=$(mktemp -t changelog-theirs.XXXXXXXX.md)
git show :2:plugins/soleur/CHANGELOG.md > "$ours"
git show :3:plugins/soleur/CHANGELOG.md > "$theirs"
echo "ours=$ours theirs=$theirs"  # echo the paths: the Read/Write steps below need them, and a separate tool call does not inherit these vars

• :2: is "ours" (feature branch)
• :3: is "theirs" (main)

Read both files. Reconstruct the complete CHANGELOG:

• Keep the file header (title, description, links)
• Merge version entries in descending version order
• If the feature branch has a draft entry, keep it
• All entries from main must be preserved

Write the complete reconstructed file. Then verify integrity:

wc -l plugins/soleur/CHANGELOG.md

The line count should be roughly the sum of unique lines from both sides. If the result is suspiciously short (less than 80% of the larger input file), something was truncated -- stop and report.

git add plugins/soleur/CHANGELOG.md

3.3 Claude-assisted resolution

For non-version-file conflicts, read the conflicted file and resolve based on intent:

1. Read the file with conflict markers
2. Understand what each side changed and why
3. Resolve the conflict preserving the intent of both changes
4. Write the resolved file

If resolution confidence is low (ambiguous intent, large conflict spanning many lines, or the changes are contradictory), abort the entire merge:

git merge --abort

Then stop:

STOPPED: Could not confidently resolve conflict in: <file>
The merge has been aborted. Working tree is clean at the starting SHA.

Conflicted files:
<list>

Resolve manually, then re-run /soleur:merge-pr.

3.4 Commit resolved conflicts

After all conflicts are resolved:

git commit -m "merge: resolve conflicts with origin/main"

Phase 4: Push and PR

Push the branch to remote:

git push -u origin <branch-name>

Replace <branch-name> with the actual branch name.

Check for an existing PR:

gh pr list --head <branch-name> --json number,state | jq '.[] | select(.state == "OPEN") | .number'

If a PR exists: Announce the PR number and proceed.

If no PR exists: Before creating, detect associated issue numbers from the branch name (e.g., fix/123-desc) and commit messages (git log origin/main..HEAD --oneline). Then create the PR:

gh pr create --title "<type>: <description>" --body "
## Summary
<bullet points summarizing changes>

Closes #ISSUE_NUMBER

## Test plan
- [ ] CI passes
- [ ] Manual verification of merge pipeline

Generated with [Claude Code](https://claude.com/claude-code)
"

If an issue number was detected, include the Closes #N line. If none, omit it. Derive the title from the branch name and changes. Use feat: for features, fix: for bug fixes.

Announce the PR URL.

Phase 5: CI and Merge

5.1 Queue Auto-Merge

SS_LIB="${CLAUDE_PLUGIN_ROOT:-./plugins/soleur