synaptiai 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:
- Parse — extract the ours block (
<<<<<<<to=======) and theirs block (=======to>>>>>>>) - Identify intent — what was each side trying to accomplish?
- 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
- Apply — write the resolved content, removing all conflict markers
- 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:
- Show the user what was deleted and what was modified
- Present options:
- Keep the modified version
- Accept the deletion
- Keep modified version in a new location (if file was moved)
- 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 togh-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) |