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:

# 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

Conflict Complexity Classification

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

Resolution Strategies

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

1. Apply — write the resolved content, removing all conflict markers
2. 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)

1. 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

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

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

2. Stage and Complete

# Stage resolved files
git add <resolved-files>

# Complete the merge or rebase
git commit --no-edit   # or GIT_EDITOR=true 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:

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

Rationalization Prevention

Watch for these shortcuts that lead to incorrect resolutions:

Configuration

Read conflict resolution settings using the three-tier cascade:

# Read conflictResolution.autoResolveTrivial (local > project > user > default)
AUTO_RESOLVE=$(jq -r '.conflictResolution.autoResolveTrivial // empty' .claude/settings.gh-workflow.local.json 2>/dev/null)
[ -z "$AUTO_RESOLVE" ] && AUTO_RESOLVE=$(jq -r '.conflictResolution.autoResolveTrivial // empty' .claude/settings.gh-workflow.json 2>/dev/null)
[ -z "$AUTO_RESOLVE" ] && AUTO_RESOLVE=$(jq -r '.conflictResolution.autoResolveTrivial // empty' "$HOME/.claude/settings.gh-workflow.json" 2>/dev/null)
[ -z "$AUTO_RESOLVE" ] && AUTO_RESOLVE="true"

# Read conflictResolution.maxConflictFiles
MAX_FILES=$(jq -r '.conflictResolution.maxConflictFiles // empty' .claude/settings.gh-workflow.local.json 2>/dev/null)
[ -z "$MAX_FILES" ] && MAX_FILES=$(jq -r '.conflictResolution.maxConflictFiles // empty' .claude/settings.gh-workflow.json 2>/dev/null)
[ -z "$MAX_FILES" ] && MAX_FILES=$(jq -r '.conflictResolution.maxConflictFiles // empty' "$HOME/.claude/settings.gh-workflow.json" 2>/dev/null)
[ -z "$MAX_FILES" ] && MAX_FILES="20"

Integration Points

This skill provides domain knowledge for:

• gh-resolve — conflict analysis, classification, resolution strategies, and verification (loaded as context)
• gh-merge — conflict detection triggers handoff to gh-resolve

The skill's content informs:

• Per-file resolution strategy selection
• User decision points (delete-modify, competing changes)
• Post-resolution quality verification

Graceful Degradation