Resolve merge conflicts

Contract

Field	Bound contract
Trigger	A merge, rebase, cherry-pick, or stash pop stops on conflicts: git exits with unmerged paths.
Authority	Reversible local: writes only conflicted-file edits, staged resolutions, regenerated lockfiles, and integration continuation (committing a merge, git rebase --continue, git cherry-pick --continue, and git stash drop only after the resolution is committed); runs scoped checks; rollback is git merge --abort, git rebase --abort, git cherry-pick --abort, or git checkout -- <file>. No remote mutation. No push, no tag, no force-push.
Side effect	Edits conflicted files, stages resolutions, regenerates lockfiles with package manager tooling, runs scoped checks, completes the in-progress integration.
Done	No unmerged paths, no conflict markers in any tracked file, scoped checks pass, integration is committed and complete.

Refusal

Not for people-mediation or team-interpersonal conflicts; use culture-conflict-mediation, which addresses working friction between colleagues using Culture Index trait profiles; resolve-merge-conflicts handles text conflicts in tracked files where git stops on unmerged paths. The shared word "conflict" is the only overlap. Not for remote, credential, publish, deploy, or other irreversible changes.

Inputs

The repository root and the set of conflicting files are supplied by the in-progress git state. git status and git diff --name-only --diff-filter=U are authoritative for the conflict list.

Optional context:

• Ancestor / theirs / yours: git show :1:<file>, git show :2:<file>, git show :3:<file>.
• Validation command: any command the human specifies; otherwise discover the project's own type checker, tests, and formatter.

Procedure

1. Detect the conflict state. Run git status. Identify which integration is in progress (merge, rebase, cherry-pick, or stash pop) and enumerate the unmerged paths. If zero unmerged paths, the trigger condition is not met; stop. Done when: the conflict-stop type is named and every unmerged path is listed.

2. Gather context for each conflicted file. Read the three versions, ancestor (:1:), theirs (:2:), yours (:3:), via git show. Use read with the :conflicts selector to enumerate marker blocks; fall back to ranged read calls for files the selector returns empty. Use difft for side-by-side comparison when either intent is unclear. Done when: every conflicted file's three versions and conflict-marker blocks have been examined.

3. Read the primary sources for both sides. Read the commit messages, pull requests, and original issues or tickets for both changes. State why each side exists in one sentence before editing any hunk. If neither side's commit, PR, or linked issue expresses a clear intent, stop and report the ambiguous files, asking the human to supply the missing intent before continuing; do not guess an intent to drive the resolution. Done when: each side's intent is stated and recorded, or ambiguous files are reported and the skill pauses for human input.

4. Resolve each hunk. Preserve both intents when they fit together. When they genuinely conflict, choose the side that matches the integration's stated goal, name the trade-off, and record the discarded intent so the finishing commit message can name both sides' intents and the resolution rationale. Invent no new behaviour. Remove all conflict markers from each resolved file. Done when: no conflict markers remain in any tracked file and every conflict resolution has its trade-off and any discarded intent recorded.

5. Regenerate lockfiles with tooling. If a lockfile is among the conflicting files, regenerate it with the project package manager rather than hand-editing. Done when: lockfiles are regenerated, or confirmed not among the conflicted set.

6. Stage resolved files. Run git add <file> for each resolved file. Confirm git status shows zero unmerged paths. Done when: no unmerged paths remain in git status.

7. Run scoped checks. Discover the repository's own commands. Run the type checker, tests, and formatter in that order when they exist. Scope runs to the resolution; fix only failures introduced by the integration. If a pre-existing failure blocks progress, stop and report it without suppressing or working around it. Done when: scoped checks pass, or pre-existing failures are reported without suppression.

8. Finish the integration. Complete the in-progress operation:

   • Merge: commit the merge with a message that names both sides' intents and the resolution rationale, including any discarded intent recorded in Step 4.
   • Rebase: git rebase --continue until every commit is replayed and no conflict remains.
   • Cherry-pick: git cherry-pick --continue (or commit, then continue if multiple commits remain).
   • Stash pop: the stash is applied after resolution; run git stash drop only after the resolved changes are committed, so the stash stays recoverable until the resolution is in history. Done when: git status shows no conflicts and the integration is complete.

Failure and recovery

Failure class	Condition	Recovery
No conflict present	git status reports zero unmerged paths	Stop; trigger condition not met
Unresolvable hunk	Both sides are logically incompatible without introducing incorrect behaviour	Leave the file marked, do not stage it, report the hunk and the competing intent
Lockfile regeneration fails	Package manager cannot regenerate the lockfile	Do not hand-edit the lockfile; report the failure and leave it unresolved
Scoped check failure	A check introduced by the integration fails	Fix only integration-introduced failures; report pre-existing failures without suppression
Unresolved marker	Any <<<<<<< found after staging	Stop; report the path and line range
Intent ambiguity	Neither side's commit, PR, or linked issue expresses a clear intent	Stop; report the ambiguous files and ask the human to supply the missing intent before continuing
Scope creep	Resolving one conflict reveals additional unrelated conflicts or issues	Stop at the current merge/rebase/cherry-pick/stash scope; do not refactor, clean up, or fix code outside the conflicted hunks
Non-convergence	Two resolution attempts produce the same check failure	Stop; report the conflict pair, both attempted resolutions, and the failure output

Partial-result rule: If fewer than all conflicted files are resolved, the run is incomplete. Do not commit, do not claim success. Report every unresolved hunk by file and line range.

Rollback (user-requested only): git merge --abort, git rebase --abort, git cherry-pick --abort restore the pre-conflict VCS state at any point before a commit is made. git checkout -- <file> discards a staged-but-uncommitted resolution for a single file. A hard git reset --hard is never offered as a recovery path; it is the user's own action if they choose it.

Output

A per-file report listing each resolved hunk, the chosen resolution, and any unresolved remainder; lockfile regeneration result; scoped-check outcome (pass or named failure); final git status summary.