merge-conflict-resolution git:20260312.7a9753fA

Immutable. This exact content is served forever at /api/v1/blob/b51b5d085e29314b.

---
name: merge-conflict-resolution
description: "Detect, classify, and resolve git merge conflicts through structured analysis of conflict markers, per-file strategy selection, and post-resolution verification. Use when a branch has conflicts with its merge target or when rebasing onto an updated base."
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TaskCreate, TaskList, TaskUpdate, AskUserQuestion
context: fork
agent: general-purpose
---

# Merge Conflict Resolution

Domain skill for detecting, classifying, and resolving git merge conflicts systematically.

## Iron Law

**NEVER silently drop changes.** Every conflict resolution must account for both sides. If lines from either side are excluded, the rationale must be documented. When in doubt, ask the user rather than guess.

## Conflict Detection

Detect conflicted files and their conflict types:

```bash
# List files with unmerged entries
git diff --name-only --diff-filter=U

# Full status with conflict markers
git status --porcelain
```

Classify each file by its porcelain status prefix.

## Conflict Type Classification

| Status | Type | Description |
|--------|------|-------------|
| UU | Content | Both sides modified the same file |
| AA | Add-add | Both sides added a file with the same name |
| UD | Delete-modify (ours deleted) | We deleted, they modified |
| DU | Delete-modify (theirs deleted) | They deleted, we modified |
| AU | Rename-related (add/unmerged) | Rename collision |
| UA | Rename-related (unmerged/add) | Rename collision |

## Conflict Complexity Classification

Assess each conflicted file's complexity before choosing a strategy:

| Complexity | Description | Example |
|------------|-------------|---------|
| Trivial | Non-overlapping changes in different sections | Import added at top + function added at bottom |
| Semantic | Changes to the same logical unit | Both sides modify the same function |
| Structural | File was refactored on one side | Moved code, renamed variables, changed structure |
| Delete-modify | One side deleted what the other modified | Feature removed vs feature enhanced |

## Resolution Strategies

| Strategy | When to Use | Risk | Autonomy |
|----------|-------------|------|----------|
| accept-ours | Their change is superseded by ours | Low | Tier 1 for trivial |
| accept-theirs | Our change is superseded by theirs | Low | Tier 1 for trivial |
| manual-merge | Both changes are needed | Medium | Tier 2 — show rationale |
| rebase | Clean linear history needed, few conflicts | Medium | Tier 2 — show rationale |

## Manual Merge Algorithm

For each conflict hunk in a file:

1. **Parse** — extract the ours block (`<<<<<<<` to `=======`) and theirs block (`=======` to `>>>>>>>`)
2. **Identify intent** — what was each side trying to accomplish?
3. **Classify compatibility**:
   - **Compatible**: both changes can coexist (e.g., different imports, non-overlapping logic) → combine both
   - **Competing**: changes are mutually exclusive (e.g., different implementations of the same function) → ask user
4. **Apply** — write the resolved content, removing all conflict markers
5. **Verify** — confirm no orphaned markers remain in the file

## Delete-Modify Protocol

When one side deletes a file (or section) that the other side modifies:

1. Show the user what was deleted and what was modified
2. Present options:
   - Keep the modified version
   - Accept the deletion
   - Keep modified version in a new location (if file was moved)
3. Wait for user decision — never auto-resolve delete-modify conflicts

## Post-Resolution Verification

After resolving all conflicts, run these checks in order:

### 1. Orphaned Marker Audit

```bash
# Must return zero results
grep -rn '<<<<<<<\|=======\|>>>>>>>' --include='*' . 2>/dev/null | grep -v '.git/' | grep -v 'node_modules/'
```

If any markers remain, resolution is incomplete. Fix before proceeding.

### 2. Stage and Complete

```bash
# Stage resolved files
git add <resolved-files>

# Complete the merge or rebase
git merge --continue   # or git rebase --continue
```

### 3. Build and Test Verification

Run the project's quality commands (lint, test, typecheck) to verify the resolution didn't break anything. Use capability-discovery to find available commands.

### 4. Resolution Diff Display

Show a summary of what was resolved:

```bash
# Show what changed in the resolution
git diff HEAD~1 --stat
```

## Rationalization Prevention

Watch for these shortcuts that lead to incorrect resolutions:

| Rationalization | Correct Response |
|----------------|-----------------|
| "Just take ours for everything" | Analyze each conflict individually — theirs may contain important changes |
| "Too complex, just reset and start over" | Read both sides first — most conflicts are simpler than they appear |
| "Tests pass so the resolution is correct" | Review the diff too — passing tests don't guarantee semantic correctness |
| "This file isn't important" | Every file in the conflict list matters — verify or explicitly document why it's safe to skip |
| "Same change on both sides" | Verify they're truly identical — similar-looking changes may have subtle differences |