Agent skill
merge-conflict-resolution
Use when git merge or rebase fails with conflicts, you see 'unmerged paths' or conflict markers (<<<<<<< =======), or need help resolving conflicted files
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/merge-conflict-resolution
SKILL.md
Merge Conflict Resolution
Invariant Principles
- Synthesis over selection - Never pick sides. Create third option combining both intents.
--ours/--theirs= amputation. - Intent preservation - Both branches represent valuable parallel work. Understand WHY each changed before touching code.
- Surgical precision - Line-by-line edits, never wholesale replacement. >20 line changes require explicit approval.
- Evidence-based decisions - Tests exist for reasons. Deleting tested code = breaking expected behavior. Check first.
- Consent before loss - User must explicitly approve any code removal after understanding tradeoffs.
Inputs
| Input | Required | Description |
|---|---|---|
conflict_files |
Yes | List of files with merge conflicts (from git status) |
merge_base |
Yes | Common ancestor commit (from git merge-base) |
ours_branch |
Yes | Current branch name |
theirs_branch |
Yes | Branch being merged |
Outputs
| Output | Type | Description |
|---|---|---|
resolution_plan |
Inline | Per-file synthesis strategy with base/ours/theirs analysis |
resolved_files |
Files | Conflict-free source files with synthesized changes |
verification_report |
Inline | Test results, lint status, behavior confirmation |
Reasoning Schema
Proceed only when synthesis strategy clear and surgical.
Conflict Classification
| Type | Files | Resolution |
|---|---|---|
| Mechanical | Lock files, changelogs, test fixtures | Auto: regenerate locks, chronological changelog merge |
| Binary | Images, compiled assets | Ask user to choose (synthesis impossible) |
| Complex | Source, configs, docs | 3-way analysis + synthesis required |
Resolution Workflow
- Detect: List conflicted files, classify mechanical/complex
- Analyze: 3-way diff (base vs ours vs theirs) per file
- Auto-resolve: Mechanical files only
- Plan: Synthesis strategy per complex file, present for approval
- Execute: Surgical edits after explicit approval
- Verify: Tests pass, lint clean, behavior preserved
Common Patterns
| Pattern | Resolution |
|---|---|
| Both modified same function | Merge both changes (logging AND error handling) |
| Delete vs modify | Apply modification to new location |
| Same name, different purpose | Rename to distinguish |
| Same name, same purpose | True merge into unified implementation |
Anti-Patterns
Red Flags (STOP immediately)
| Thought | Reality |
|---|---|
| "User said simplify, so use theirs" | Simplify = new third option simpler than EITHER |
| "Basically the same" | Conflict exists because they differ |
| "I'll adopt their approach" | --theirs with extra steps |
| "Tests need updating anyway" | Understand test purpose first |
| "This is cleaner" | Cleaner is not the goal. Preserving both intents is. |
Question Format
| Bad (binary, over-interpreted) | Good (surgical, specific) |
|---|---|
| "Ours or theirs?" | "What specifically needs to change?" |
| "Is master's better?" | "What from master should we adopt?" |
| "Should I simplify?" | "Which specific lines are unnecessary?" |
Binary questions get binary answers, then extrapolate to wholesale changes never approved.
Stealth Amputation Trap
Accidental --theirs without command:
- Ask binary question about complex code
- Get partial answer about ONE aspect
- Interpret as approval for EVERYTHING
Prevention: Approval for ONE aspect is NOT approval for all. Each deletion requires separate verification.
Acceptable Amputation Cases
Only with explicit user consent after tradeoff explanation:
- Binary files (no synthesis possible)
- Generated files (will regenerate)
- User explicitly requests after understanding loss
Plan Template
## Resolution: [filename]
**Base:** [original state]
**Ours:** [change + intent]
**Theirs:** [change + intent]
**Synthesis:** [how combining both]
**Risk:** [edge cases, concerns]
Self-Check
Before completing resolution:
- All conflicts resolved (no
<<<<<<<markers remain) - Tests pass (both ours and theirs functionality)
- Lint/build clean
- No tested code deleted without test updates
- Behavior from both branches present
- User approved specific changes (not extrapolated)
- Synthesis achieved, not selection
If ANY unchecked: STOP and fix.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?