troykelly/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