name: merge-pr description: Workflow skill for safely merging pull requests after verification license: MIT metadata: category: workflow audience: agents, scripts, CI composed-from: - pull-request-tool - sequential-execution aspects: - interaction-modes decisions: - id: merge_readiness trigger: after-verification yolo: [proceed_if_checks_pass] collaborative: prompt: "Merge readiness decision" resume: "Proceed with selected action" options: - id: merge_squash label: "Merge with squash" action: merge --squash - id: merge_rebase label: "Merge with rebase" action: merge --rebase - id: create_draft label: "Mark as draft" action: mark-draft - id: custom label: "Other action..." allow_freeform: true

Merge PR

A workflow skill that safely merges pull requests after comprehensive verification of readiness.

Purpose

Automates the PR merge process with proper safety checks, ensuring all requirements are met before merging.

When to Use

Use this workflow when:

PR is ready to be merged to main branch
You want automated verification before merge
Need to ensure all checks pass
Want consistent merge process across team

Skill Composition

This workflow composes:

pull-request-tool: Check PR status, verify checks, execute merge
sequential-execution: Step through verification stages
yolo OR collaborative: Execution mode (autonomous vs interactive)

Parameters

Required

pr-number: Pull request number to merge
repository: Repository in format owner/repo

Optional

interaction-mode: yolo (autonomous) or collaborative (ask before merge)
merge-method: merge (default), squash, or rebase
delete-branch: Delete branch after merge (default: true)
auto-merge: Enable auto-merge if checks pending (default: false)
require-reviews: Minimum required approvals (default: 1)
require-checks: Require all status checks pass (default: true)

Workflow Steps

Phase 1: Test Parity Gate (Mandatory)

Before any PR verification, enforce the Test Parity Gate:

Run local CI tests (validating-changes aspect)
- Execute pnpm test:affected:ci on the feature branch
- If tests fail: Stop and report failure (do not proceed to merge)
- If tests pass: Continue to Phase 2
Verify no unintended deletions (guarding-branches aspect)
- Run git diff origin/main...HEAD --name-status | grep '^D'
- If deletions found: Verify they are intentional (check work item acceptance criteria)
- If deletions are unintended: Stop and report (do not merge)
- If deletions are intentional: Continue to Phase 2

Rationale: This gate ensures that before any GitHub PR verification, the code has been validated locally and matches the work item scope. Prevents merging code that fails CI locally (which should have been caught in prior phases).

Phase 2: Pre-Merge Verification

Fetch PR details
- Get PR metadata
- Verify PR is open
- Check base and head branches
Verify approvals
- Check review status
- Count approvals
- Verify required approvals met
- Check for blocking reviews
Check status
- Verify mergeable state
- Check for merge conflicts
- Verify branch is up to date
Verify CI checks (guarding-branches aspect)
- List all status checks
- Verify required checks pass
- Check for failing checks
- Ensure no pending required checks
Check review threads
- Verify no unresolved threads (or policy allows)
- Check for blocking comments

Phase 3: Merge Decision

Determine merge readiness

PR is ready to merge if:
- ✅ Mergeable state is CLEAN or UNSTABLE (no conflicts)
- ✅ Required approvals received
- ✅ All required status checks pass
- ✅ No blocking review comments
- ✅ Branch protection rules satisfied
Select merge method
- Use specified merge-method parameter
- Or infer from repo settings/history
- Default to squash if uncertain

Phase 4: Execution

Execute merge (if ready)

YOLO mode:
- Merge immediately if all checks pass
- Report success or failure
Collaborative mode:
- Show merge summary
- Request confirmation
- Execute after approval
Post-merge cleanup
- Invoke feature-branch-management cleanup to delete feature branch (local and remote)
- Verify merge succeeded
- Check main branch updated
- Prune remote tracking branches

Phase 5: Finalization

Verify completion
- Confirm PR status is merged
- Verify commit appears in main
- Check branch deleted if requested
Report results
- Summarize merge operation
- Report any issues
- Provide next steps if needed

Interaction Modes (Aspect)

This skill uses the interaction-modes aspect for decision handling.

Aspect: interaction-modes
Decision point: merge_readiness
Parameter: interaction-mode = yolo | collaborative

Merge Methods

Merge Commit (--merge)

Creates merge commit
Preserves full history
Use when: History context important

Squash and Merge (--squash)

Combines all commits into one
Clean linear history
Use when: Feature commits not important

Rebase and Merge (--rebase)

Replays commits on base
Linear history, preserves commits
Use when: Clean history with commit granularity

Auto-Merge Option

When auto-merge = true:

Enables GitHub auto-merge feature
PR will merge automatically when checks pass
Useful for:
- PRs with pending checks
- Dependabot updates
- Automated workflows

Verification Checklist

Before merging, verify:

PR is open (not closed/merged already)
No merge conflicts
Required approvals received
All required status checks pass
No blocking review comments
Branch protection rules satisfied
Correct base branch (usually main)
Changes reviewed and acceptable

Error Handling

Common Issues and Resolutions

Merge conflicts
- YOLO: Report blocker, cannot proceed
- Collaborative: Suggest rebasing or conflict resolution
- Manual intervention required
Failing status checks
- YOLO: Wait or report blocker
- Collaborative: Show failing checks, ask to wait or investigate
- Auto-merge option: Enable auto-merge to merge when passes
Missing approvals
- YOLO: Report blocker, request reviews
- Collaborative: Show who can approve, ask to request
- Cannot proceed without required approvals
Unresolved threads
- YOLO: Attempt to resolve if trivial, otherwise report
- Collaborative: Show threads, ask to resolve
- Policy-dependent: Some repos allow merging with unresolved
Branch protection violations
- Report specific requirement not met
- Cannot override (requires admin)
- Must satisfy all rules

Best Practices

Always verify checks: Never merge with failing tests
Respect approvals: Ensure required reviews complete
Clean up branches: Delete after merge to reduce clutter
Use appropriate method: Match repo conventions
Verify conflicts: Check mergeable state first
Update main locally: Pull after merging
Notify team: Communication for significant merges
Tag releases: Create tags for versioned merges

Safety Guards

Even in YOLO mode, never:

❌ Merge with failing required checks
❌ Merge without required approvals
❌ Merge with conflicts
❌ Override branch protection
❌ Skip verification steps

Always:

✅ Verify PR is ready
✅ Check all status checks
✅ Confirm approvals present
✅ Use safe merge method
✅ Report any issues

Output Format

YOLO Mode Output

TASK: Merge PR #42
STATUS: Success

VERIFICATION:
✅ Approvals: 2/1 required
✅ Status Checks: 8/8 passing
✅ Merge Conflicts: None
✅ Branch Protection: Satisfied

MERGE:
Method: Squash and merge
Commit: abc1234
Branch: feature-xyz (deleted)

RESULT: PR #42 successfully merged to main

Collaborative Mode Output

PR Merge Readiness (#42)

Status Checks:
✅ CI Tests (3m 24s)
✅ Linter (45s)
✅ Security Scan (1m 12s)
❌ Integration Tests (failed)

Current Status: NOT READY
Blocker: Integration tests failing

Recommended action: Fix test failures or investigate

Would you like me to:
A) Show test failure details
B) Wait for checks to be fixed and retry
C) Cancel merge operation

Integration Example

# Full PR workflow using composed skills

1. process-pr (parent workflow)
2. resolve-pr-comments
   - Address all feedback
3. merge-pr (this workflow)
   - Verify readiness
   - Execute merge

Done: PR fully processed and merged

Related Skills

pull-request-tool: Backend for PR operations (fetch, merge, verify)
feature-branch-management: Invoked after merge to clean up feature branch
process-pr: Orchestrates full PR workflow (includes merge-pr in Stage 5)
handle-pr-feedback: Addresses PR review feedback before merge
updating-work-item: Updates work item status after PR merged

Quick Reference

PURPOSE:
Safely merge PR after comprehensive verification

COMPOSITION:
pull-request-tool + sequential-execution + (yolo OR collaborative)

MODES:
YOLO: Auto-merge if ready
Collaborative: Confirm before merge

PHASES:

1. Pre-Merge Verification
2. Merge Decision
3. Execution
4. Finalization

VERIFICATION:

- Mergeable state
- Required approvals
- Status checks
- No conflicts
- Branch protection

MERGE METHODS:
merge: Merge commit (preserves history)
squash: Single commit (clean history)
rebase: Linear history (preserves commits)

PARAMETERS:
pr-number: Required
repository: Required (owner/repo)
interaction-mode: yolo or collaborative
merge-method: merge/squash/rebase
delete-branch: true (default)
auto-merge: false (default)

SAFETY:
Never merge with:

- Failing required checks
- Missing approvals
- Merge conflicts
- Branch protection violations

Name	merge-pr
Description	Workflow skill for safely merging pull requests after verification

merge-pr

SKILL.md