synaptiai/merge-conflict-resolution

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

| 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 | Auto for trivial | | accept-theirs | Our change is superseded by theirs | Low | Auto for trivial | | manual-merge | Both changes are needed | Medium | Show rationale | | rebase | Clean linear history needed, few conflicts | Medium | 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

# 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:

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

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

| Missing Capability | Fallback | |-------------------|----------| | No capability-discovery | Detect quality commands from tech stack indicators | | No quality commands found | Skip build/test verification, warn user | | AskUserQuestion unavailable | Default to manual-merge for all non-trivial conflicts | | Config files missing | Use defaults (autoResolveTrivial: true, maxConflictFiles: 20) |