Merge Conflict Resolution
Resolve conflicts by understanding BOTH sides' intent, then reconstructing what
the code should be — never by picking a side blindly or deleting markers.
Iron Rules
- Never resolve a conflict you do not understand; investigate until you do.
- Never just delete
<<<<<<< markers keeping one side by default.
- After resolving every file, the branch must build and pass tests BEFORE
git continue/commit.
Workflow
1. Establish Context
git status # which files, which operation (merge/rebase/cherry-pick)
git log --oneline --all -15 --graph # what is meeting what
git log MERGE_HEAD -5 # incoming side (during merge); rebase refs differ
Know: what change am I integrating into what? Read both commit messages.
2. Triage Conflicted Files
git diff --name-only --diff-filter=U
Classify each:
| Type |
Examples |
Strategy |
| Trivial |
whitespace, imports order, lockfiles |
mechanical union or regenerate |
| Textual overlap |
both edited different parts of same area |
often both-keep with ordering thought through |
| Semantic collision |
both changed same logic differently |
requires intent reconstruction |
| Delete/edit |
one side deleted, other modified |
decide fate from WHY it was deleted |
| Binary/generated |
images, package-lock.json, builds |
regenerate via toolchain, never hand-edit |
Resolve trivial ones first to shrink the problem.
3. Resolve By Intent
For each real conflict:
- Read ours context: surrounding function + its tests + recent commits
touching it (
git log -p <file> -5).
- Read theirs intent: same for incoming side.
- Ask: what SHOULD this code be now that both changes exist? The answer is
usually a synthesis, sometimes a superset, rarely either raw side.
- Edit to the resolved version, remove ALL markers, keep formatting sane.
When genuinely ambiguous (both sides ship different behaviors users may depend
on): STOP and ask the user. Present both intents in one sentence each.
Special cases:
- Lockfiles: delete and regenerate (
npm install, pnpm install), never merge.
- Rename storms:
git log --follow to track moved files; resolve at new paths.
- Rebase conflicts repeat per commit: consider
git rebase --onto or merging
instead if the same file conflicts >2 times; report the pain.
4. Verify Before Continuing
Check resolved files for stray markers, then:
- Build/typecheck passes
- Test suite passes (at least affected areas)
git add <resolved files>
Only then git merge --continue / git rebase --continue. For aborts,
git merge --abort / git rebase --abort restores pre-conflict state cleanly —
offer this when the user prefers to redo differently.
5. Report
Summarize per file: conflict type, how resolved (both-kept / theirs / ours /
regenerated / asked-user), and any follow-ups (e.g. "their refactor renamed X;
callers updated").
Guardrails
- No force-pushes during conflict work unless user explicitly demands it.
- Do not silently drop one side's behavior; that is how production bugs are born.
- Generated files: always regenerate, never negotiate line-by-line.
- If conflicts reveal diverging architecture, surface it — maybe the merge
should not happen yet (
codebase-design conversation).
Related Skills
systematic-debugging - when post-merge tests fail mysteriously
bug-diagnosis - if a conflict resolution itself introduced a bug
requesting-code-review - high-risk resolutions deserve review before push
1---2name: merge-conflict-resolution3description: >-4 Resolve git merge/rebase conflicts systematically without losing either5 side's intent. Use when the user says fix this merge conflict, resolve the6 rebase, there are conflicts, git is stuck on a conflict, or after pulling/7 rebasing/merging when markers appear. Covers reading both sides' intent,8 semantic (not just textual) resolution, and verification before continuing.9license: MIT10metadata:11 source: https://skillmd.com/skills/hongyime/merge-conflict-resolution12 author: Local setup13 version: "1.0.1"14 platform: "Codex, Antigravity (agy), OpenCode, Muse on Windows, macOS, Linux (Debian)"15---1617# Merge Conflict Resolution1819Resolve conflicts by understanding BOTH sides' intent, then reconstructing what20the code should be — never by picking a side blindly or deleting markers.2122## Iron Rules23241. Never resolve a conflict you do not understand; investigate until you do.252. Never just delete `<<<<<<<` markers keeping one side by default.263. After resolving every file, the branch must build and pass tests BEFORE27 `git continue`/commit.2829## Workflow3031### 1. Establish Context3233```bash34git status # which files, which operation (merge/rebase/cherry-pick)35git log --oneline --all -15 --graph # what is meeting what36git log MERGE_HEAD -5 # incoming side (during merge); rebase refs differ37```3839Know: what change am I integrating into what? Read both commit messages.4041### 2. Triage Conflicted Files4243```bash44git diff --name-only --diff-filter=U45```4647Classify each:4849| Type | Examples | Strategy |50|---|---|---|51| Trivial | whitespace, imports order, lockfiles | mechanical union or regenerate |52| Textual overlap | both edited different parts of same area | often both-keep with ordering thought through |53| Semantic collision | both changed same logic differently | requires intent reconstruction |54| Delete/edit | one side deleted, other modified | decide fate from WHY it was deleted |55| Binary/generated | images, `package-lock.json`, builds | regenerate via toolchain, never hand-edit |5657Resolve trivial ones first to shrink the problem.5859### 3. Resolve By Intent6061For each real conflict:62631. **Read ours context:** surrounding function + its tests + recent commits64 touching it (`git log -p <file> -5`).652. **Read theirs intent:** same for incoming side.663. **Ask:** what SHOULD this code be now that both changes exist? The answer is67 usually a synthesis, sometimes a superset, rarely either raw side.684. Edit to the resolved version, remove ALL markers, keep formatting sane.6970When genuinely ambiguous (both sides ship different behaviors users may depend71on): STOP and ask the user. Present both intents in one sentence each.7273Special cases:7475- **Lockfiles:** delete and regenerate (`npm install`, `pnpm install`), never merge.76- **Rename storms:** `git log --follow` to track moved files; resolve at new paths.77- **Rebase conflicts repeat per commit:** consider `git rebase --onto` or merging78 instead if the same file conflicts >2 times; report the pain.7980### 4. Verify Before Continuing8182Check resolved files for stray markers, then:83841. Build/typecheck passes852. Test suite passes (at least affected areas)863. `git add <resolved files>`8788Only then `git merge --continue` / `git rebase --continue`. For aborts,89`git merge --abort` / `git rebase --abort` restores pre-conflict state cleanly —90offer this when the user prefers to redo differently.9192### 5. Report9394Summarize per file: conflict type, how resolved (both-kept / theirs / ours /95regenerated / asked-user), and any follow-ups (e.g. "their refactor renamed X;96callers updated").9798## Guardrails99100- No force-pushes during conflict work unless user explicitly demands it.101- Do not silently drop one side's behavior; that is how production bugs are born.102- Generated files: always regenerate, never negotiate line-by-line.103- If conflicts reveal diverging architecture, surface it — maybe the merge104 should not happen yet (`codebase-design` conversation).105106## Related Skills107108- `systematic-debugging` - when post-merge tests fail mysteriously109- `bug-diagnosis` - if a conflict resolution itself introduced a bug110- `requesting-code-review` - high-risk resolutions deserve review before push