conflict-resolution

name	conflict-resolution
description	Use when encountering merge conflicts - handle conflicts cleanly, verify resolution, and maintain code integrity

Conflict Resolution

Overview

Handle merge conflicts systematically to maintain code integrity.

Core principle: Conflicts require careful resolution, not just picking one side.

Announce at start: "I'm using conflict-resolution to handle these merge conflicts."

When Conflicts Occur

Conflicts happen when:

Situation	Example
Rebasing on updated main	git rebase origin/main
Merging main into branch	git merge origin/main
Cherry-picking commits	git cherry-pick [sha]
Pulling with local changes	git pull

The Resolution Process

Conflict Detected
       │
       ▼
┌─────────────────┐
│ 1. UNDERSTAND   │ ← What's conflicting and why?
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 2. ANALYZE      │ ← Review both versions
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. RESOLVE      │ ← Make informed decision
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. VERIFY       │ ← Tests pass, code works
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 5. CONTINUE     │ ← Complete the operation
└─────────────────┘

Step 1: Understand the Conflict

See Conflicting Files

# List files with conflicts
git status

# Output shows:
# Unmerged paths:
#   both modified:   src/services/user.ts
#   both modified:   src/utils/validation.ts

View the Conflict

# See the conflict markers
cat src/services/user.ts

<<<<<<< HEAD
// Your changes
function createUser(data: UserData): User {
  return { ...data, id: generateId() };
}
=======
// Their changes (main branch)
function createUser(data: UserData): Promise<User> {
  return db.create({ ...data, id: generateId() });
}
>>>>>>> main

Understand the History

# See what changed in each branch
git log --oneline --left-right HEAD...main -- src/services/user.ts

# See the actual changes
git diff HEAD...main -- src/services/user.ts

Step 2: Analyze Both Versions

Questions to Answer

Question	Consider
What was the intent of your change?	Your feature/fix
What was the intent of their change?	Their feature/fix
Are they mutually exclusive?	Can both coexist?
Which is more recent/correct?	Check issue references
Do both need to be kept?	Merge the logic

Compare Approaches

## Conflict Analysis: src/services/user.ts

### My Change (feature/issue-123)
- Made createUser synchronous
- Reason: Simplified for local testing
- Issue: #123

### Their Change (main)
- Made createUser async with DB
- Reason: Production database integration
- Issue: #456

### Resolution
Keep their async version (production requirement).
My testing simplification should use mocks instead.

Step 3: Resolve the Conflict

Resolution Strategies

Keep Theirs (Main)

When main's version is correct:

# Use their version
git checkout --theirs src/services/user.ts
git add src/services/user.ts

Keep Ours (Your Branch)

When your version is correct:

# Use your version
git checkout --ours src/services/user.ts
git add src/services/user.ts

Manual Merge (Both)

When both changes are needed:

// Remove conflict markers
// Combine both changes intelligently

// Result: Keep async from main, add your new validation
async function createUser(data: UserData): Promise<User> {
  // Your addition: validation
  validateUserData(data);

  // Their change: async DB call
  return db.create({ ...data, id: generateId() });
}

# After editing
git add src/services/user.ts

Conflict Markers

Remove ALL conflict markers:

<<<<<<< HEAD      ← Remove
=======           ← Remove
>>>>>>> main      ← Remove

The final file should have NO conflict markers.

Step 4: Verify Resolution

Syntax Check

# TypeScript: Check types
pnpm typecheck

# Or for specific file
npx tsc --noEmit src/services/user.ts

Run Tests

# Run all tests
pnpm test

# Run tests for affected area
pnpm test --grep "user"

Visual Review

# See final resolved state
git diff --cached

# Ensure no conflict markers remain
grep -r "<<<<<<" src/
grep -r "======" src/
grep -r ">>>>>>" src/

Step 5: Continue the Operation

After Rebase

# Continue the rebase
git rebase --continue

# If more conflicts, repeat resolution
# When complete:
git push --force-with-lease

After Merge

# Complete the merge
git commit -m "Merge main into feature/issue-123"

# Push
git push

Abort if Needed

If resolution goes wrong:

# Abort rebase
git rebase --abort

# Abort merge
git merge --abort

# Start fresh

Complex Conflicts

Multiple Files

Resolve one file at a time:

# See all conflicts
git status

# Resolve each
# 1. Edit file
# 2. git add file
# 3. Next file

# When all resolved
git rebase --continue

Semantic Conflicts

Sometimes code merges cleanly but is semantically broken:

// main: Function signature changed
function process(data: NewFormat): Result

// yours: Called with old format
process(oldFormatData);  // No conflict marker, but broken!

Always run tests after resolution.

Conflicting Dependencies

// package.json conflict
<<<<<<< HEAD
  "dependencies": {
    "library": "^2.0.0"
=======
  "dependencies": {
    "library": "^1.5.0"
>>>>>>> main

Resolution:

1. Choose the appropriate version
2. Delete pnpm-lock.yaml
3. Run pnpm install
4. Commit the new lock file

Best Practices

Before Resolution

• Pull latest main frequently to minimize conflicts
• Keep branches short-lived
• Communicate about shared files

During Resolution

• Take your time
• Understand both changes
• Don't just pick "ours" or "theirs" blindly
• Test after resolution

After Resolution

• Run full test suite
• Review the merged result
• Commit with clear message

Conflict Message

When conflicts occur during PR:

## Merge Conflict Resolution

This PR had conflicts with main that have been resolved.

### Conflicting Files
- `src/services/user.ts`
- `src/utils/validation.ts`

### Resolution Summary

**user.ts:**
Kept async implementation from main, added validation from this PR.

**validation.ts:**
Merged both validation rules (main added email, this PR added phone).

### Verification
- [x] All tests pass
- [x] Build succeeds
- [x] No conflict markers in code
- [x] Functionality verified manually

Checklist

When resolving conflicts:

• All conflicting files identified
• Each conflict analyzed (understood both sides)
• Resolution chosen (ours/theirs/merge)
• Conflict markers removed
• Files staged (git add)
• Tests pass
• Build succeeds
• No remaining conflict markers
• Operation completed (rebase --continue / commit)

Integration

This skill is called when:

• git rebase encounters conflicts
• git merge encounters conflicts
• PR shows conflicts

This skill ensures:

• Clean resolution
• No lost changes
• Working code after merge