Resolving Merge Conflicts

Use this workflow only while Git reports unmerged paths; ordinary code or test failures belong elsewhere.

1. Start with a compact summary of the in-progress merge/rebase and every unresolved path.

python3 ~/.claude/skills/resolving-merge-conflicts/scripts/extract_conflict_context.py --repo .

Keep the list of conflicted paths it reports; step 7 reviews each of them after they are resolved. If the list is lost once files are staged, git merge-tree --write-tree --name-only HEAD MERGE_HEAD prints it again (or git merge-tree --write-tree --name-only HEAD^1 HEAD^2 when inspecting an already-committed merge).

2. Find the primary sources for each conflict. Understand why each change was made and what the original intent was. Read the commit messages, check the PRs, and check original issues/tickets.
3. Inspect one conflicted file at a time.

python3 ~/.claude/skills/resolving-merge-conflicts/scripts/extract_conflict_context.py --repo . --file <path>

Use the compact hunk or index-stage output first. Read the full file only when the compact output is insufficient to preserve the surrounding behavior or intent. For binary, rename, or submodule conflicts, a missing text preview is not sufficient evidence: inspect the relevant index stages, object modes or commits, and history before choosing a resolution.

4. Resolve that file. Preserve both intents where possible. Where they are incompatible on a user-visible behavior (for example, one side narrows, disables, or reverses a behavior the other side added), do not silently drop one side's behavior to satisfy the other side's new test or comment—record the behavioral trade-off so step 7 surfaces it to the user. Do not invent new behavior. Always resolve; never --abort. Stage that file alone with git add -- <path> or git rm -- <path>.
5. Re-check unresolved conflicts after each file.

python3 ~/.claude/skills/resolving-merge-conflicts/scripts/extract_conflict_context.py --repo .
git diff --name-only --diff-filter=U

Repeat Steps 2–5 until both commands report no unresolved paths.

6. Discover the project's automated checks and run them—typically typecheck, tests, then format. Fix anything the merge broke, and verify no conflict markers remain in resolved text files.
7. Review every conflicted file for a side whose change disappeared. Green checks do not cover this: a resolution that keeps one side's refactor and drops the other side's addition stays green whenever nothing tested that addition. Build the three-diff bundle (base to ours, base to theirs, and base to the result) and run the mechanical checks with prepare_merge_review.py:

# In-progress merge after staging resolved files (MERGE_HEAD present):
python3 ~/.claude/skills/resolving-merge-conflicts/scripts/prepare_merge_review.py --repo . --staged --out /tmp/merge-review-bundle.txt

# Already-committed merge or delegated worker handoff (computes conflicts from HEAD^1 and HEAD^2):
python3 ~/.claude/skills/resolving-merge-conflicts/scripts/prepare_merge_review.py --repo . --commit HEAD --out /tmp/merge-review-bundle.txt

(In a rebase where REBASE_HEAD is active instead of a two-parent merge, compute base=$(git merge-base HEAD REBASE_HEAD) and produce git diff "$base" HEAD -- <path>, git diff "$base" REBASE_HEAD -- <path>, and git diff --cached "$base" -- <path> for each path from step 1.)

A file whose conflicts were all mechanical (translation dictionaries, lockfiles, a changelog, or a manifest where only version changed) is checked by a script, not an agent: every key or entry either side added is present in the result, and a key both sides changed or a manifest that also modified scripts or dependencies is kept in REVIEW_FILES_COUNT rather than exempted by filename. Lockfiles are regenerated from the merged manifests rather than checked entry by entry. When REVIEW_FILES_COUNT > 0, give both BUNDLE_PATH and BUNDLE_TOTAL_LINES to a fresh reviewer agent with no conversation context, one file per item, and instruct the reviewer to read BUNDLE_PATH continuously from line 1 through BUNDLE_TOTAL_LINES (starting with limit: 800, and if any Read fails due to token/size limits, never advance offset—retry at the same offset with a smaller limit and continue from the last line actually read so no lines are skipped), requiring one of three verdicts per file:

• PASS — every hunk from both ours and theirs is preserved, or a hunk was replaced by a structural refactor that keeps the same user-visible behavior on both sides.
• MISSING — a hunk, parameter, or call from ours or theirs disappeared by accident with no conflict trade-off (restore it and re-run step 6).
• DIVERGENCE — a user-visible behavior from ours or theirs was narrowed, disabled, or reversed in result (even when the winning side's code, comment, or test explains why that side wanted the restriction). One side's comment or test proves that side's intent, not that the user chose it over the other side's behavior.

Reading BUNDLE_PATH in the resolving session does not substitute for the fresh reviewer even when REVIEW_FILES_COUNT is 1 or the bundle is short, because the resolver already expects its resolution to be complete. Whether main resolves the merge directly or receives a commit from a delegated worker that cannot spawn subagents, main must obtain that fresh reviewer's per-file verdicts, fix every MISSING item (then re-run step 6), and surface every DIVERGENCE item to the user for a decision before the merge counts as done. Done when every conflicted path has a script or fresh-reviewer verdict, each MISSING hunk is restored, and each DIVERGENCE has the user's explicit decision. Proceed to step 8.

8. Finish the merge/rebase. Commit the completed merge. If rebasing, continue until every commit is rebased, repeating the workflow for each new conflict stop.