verification-before-merge

Verification Before Merge

Overview

Final verification before merging. All gates must pass.

Core principle: Never merge without complete verification.

This is a HARD GATE. Do not merge with any failure.

The Gates

All must be GREEN to merge:

┌──────────────────────────────────────────────────────┐
│                  MERGE GATES                         │
├──────────────────────────────────────────────────────┤
│  [ ] CI Pipeline Green                               │
│  [ ] Local Integration Tests Pass (if services)     │
│  [ ] All Tests Pass                                  │
│  [ ] Code Review Approved                            │
│  [ ] Acceptance Criteria Verified                    │
│  [ ] No Unresolved Conversations                     │
│  [ ] Branch Up to Date                               │
│  [ ] No Merge Conflicts                              │
├──────────────────────────────────────────────────────┤
│  ALL GREEN → MERGE ALLOWED                           │
│  ANY RED → MERGE BLOCKED                             │
└──────────────────────────────────────────────────────┘

Gate Details

1. CI Pipeline Green

# Check all CI checks
gh pr checks [PR_NUMBER]

# Expected: All passing
✓  build          passed
✓  lint           passed
✓  test           passed
✓  typecheck      passed
✓  security       passed

If not green: Use ci-monitoring to resolve.

1.5. Local Integration Tests Pass

CRITICAL: CI should validate, not discover. If CI found bugs, local testing was insufficient.

# Verify services are running (if project has docker-compose)
docker-compose ps

# Run integration tests against real services
pnpm test:integration

# Verify migrations work
pnpm migrate

If project has docker-compose services:

• Services MUST be running locally
• Integration tests MUST pass against real services
• Migrations MUST apply successfully
• NOT acceptable: "unit tests with mocks pass, I'll let CI verify the real services"

Local testing evidence must be posted to issue before PR creation.

Skill: local-service-testing

2. All Tests Pass

# Verify locally (CI should have done this, but verify)
pnpm test

# Check coverage
pnpm test --coverage

If failing: Fix tests before merge.

3. Code Review Approved

# Check review status
gh pr view [PR_NUMBER] --json reviews

# Expected: At least one approval, no changes requested

If not approved:

• Address feedback
• Re-request review
• Wait for approval

4. Acceptance Criteria Verified

Check the issue:

gh issue view [ISSUE_NUMBER] --json body

All acceptance criteria should be checked:

## Acceptance Criteria
- [x] User can log in
- [x] Invalid credentials show error
- [x] Session persists
- [x] Logout clears session

If not verified: Complete verification before merge.

5. No Unresolved Conversations

# Check for unresolved threads
gh pr view [PR_NUMBER] --json reviewThreads

All review comments should be:

• Resolved
• Or responded to with explanation

If unresolved: Address the feedback.

6. Branch Up to Date

# Check if branch is behind target
gh pr view [PR_NUMBER] --json mergeable,mergeStateStatus

# If behind, update
git fetch origin
git rebase origin/main
git push --force-with-lease

If not up to date: Rebase or merge target branch.

7. No Merge Conflicts

# Check for conflicts
gh pr view [PR_NUMBER] --json mergeable

If conflicts exist: Resolve before merge.

git fetch origin
git rebase origin/main
# Resolve conflicts
git add .
git rebase --continue
git push --force-with-lease

Pre-Merge Checklist

Run through this checklist before every merge:

## Pre-Merge Verification

### CI/Tests
- [ ] All CI checks passing
- [ ] Tests pass locally
- [ ] Coverage acceptable

### Review
- [ ] PR approved
- [ ] All conversations resolved
- [ ] Feedback addressed

### Verification
- [ ] All acceptance criteria verified
- [ ] Verification report posted to issue
- [ ] Issue ready to close

### Branch
- [ ] Up to date with target
- [ ] No merge conflicts
- [ ] Commits clean

### Documentation
- [ ] PR description complete
- [ ] Issue updated
- [ ] Relevant docs updated

Performing the Merge

Once all gates are green:

Using GitHub CLI

# Merge with squash (recommended for clean history)
gh pr merge [PR_NUMBER] --squash --delete-branch

# Or merge commit
gh pr merge [PR_NUMBER] --merge --delete-branch

# Or rebase
gh pr merge [PR_NUMBER] --rebase --delete-branch

Merge Strategy

Strategy	When to Use
Squash	Most PRs - creates single clean commit
Merge	When commit history is important
Rebase	When you want linear history without merge commit

Follow project conventions for merge strategy.

Post-Merge

After successful merge:

1. Verify Issue Closed

# Check issue status
gh issue view [ISSUE_NUMBER] --json state
# Should be: "CLOSED"

# If not closed automatically, close it
gh issue close [ISSUE_NUMBER] --comment "Closed by #[PR_NUMBER]"

2. Update Project Status

# Update GitHub Project fields
# Status → Done
# (Using project-status-sync)

3. Clean Up Local

# Switch to main
git checkout main

# Pull merged changes
git pull origin main

# Delete local branch
git branch -d feature/issue-123-description

# Prune remote tracking branches
git remote prune origin

4. Verify Deployment (if applicable)

If auto-deploy is configured:

• Check deployment status
• Verify feature works in deployed environment
• Monitor for errors

Merge Blocked Scenarios

Review Not Approved

Cannot merge: Review required

→ Request review
→ Address feedback
→ Get approval

Failing CI

Cannot merge: CI checks failing

→ Use ci-monitoring skill
→ Fix failures
→ Wait for green

Branch Behind

Cannot merge: Branch out of date

→ git fetch origin
→ git rebase origin/main
→ Resolve conflicts
→ git push --force-with-lease

Unresolved Conversations

Cannot merge: Unresolved review threads

→ Address each comment
→ Mark as resolved
→ Re-request review if needed

Never Merge When

Situation	Action
Tests failing	Fix tests first
CI red	Fix CI first
Review pending	Wait for review
Conflicts exist	Resolve conflicts
Acceptance criteria not met	Complete verification
Critical feedback unaddressed	Address feedback

Checklist

Final verification before clicking merge:

• All CI checks green
• Local integration tests pass (if services available)
• Local testing artifact posted to issue (if services used)
• All tests passing
• PR approved
• All conversations resolved
• Acceptance criteria verified
• Branch up to date
• No conflicts
• PR documentation complete
• Ready to close issue

Integration

This skill is called by:

• issue-driven-development - Step 13

This skill follows:

• ci-monitoring - CI is green
• pr-creation - PR exists

This skill completes:

• The development cycle for an issue