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
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.
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.
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.
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.
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.
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.
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.
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.
1---2name: resolve-merge-conflicts3description: Use when a merge, rebase, cherry-pick, or stash pop stops on conflicts. Not for people-mediation conflicts: use culture-conflict-mediation.4---56# Resolve merge conflicts78## Contract910| Field | Bound contract |11|---|---|12| Trigger | A merge, rebase, cherry-pick, or stash pop stops on conflicts: `git` exits with unmerged paths. |13| 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. |14| Side effect | Edits conflicted files, stages resolutions, regenerates lockfiles with package manager tooling, runs scoped checks, completes the in-progress integration. |15| Done | No unmerged paths, no conflict markers in any tracked file, scoped checks pass, integration is committed and complete. |1617## Refusal1819Not 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.2021## Inputs2223The 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.2425Optional context:26- Ancestor / theirs / yours: `git show :1:<file>`, `git show :2:<file>`, `git show :3:<file>`.27- Validation command: any command the human specifies; otherwise discover the project's own type checker, tests, and formatter.2829## Procedure30311. **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.32 *Done when: the conflict-stop type is named and every unmerged path is listed.*33342. **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.35 *Done when: every conflicted file's three versions and conflict-marker blocks have been examined.*36373. **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.38 *Done when: each side's intent is stated and recorded, or ambiguous files are reported and the skill pauses for human input.*39404. **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.41 *Done when: no conflict markers remain in any tracked file and every conflict resolution has its trade-off and any discarded intent recorded.*42435. **Regenerate lockfiles with tooling.** If a lockfile is among the conflicting files, regenerate it with the project package manager rather than hand-editing.44 *Done when: lockfiles are regenerated, or confirmed not among the conflicted set.*45466. **Stage resolved files.** Run `git add <file>` for each resolved file. Confirm `git status` shows zero unmerged paths.47 *Done when: no unmerged paths remain in `git status`.*48497. **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.50 *Done when: scoped checks pass, or pre-existing failures are reported without suppression.*51528. **Finish the integration.** Complete the in-progress operation:53 - Merge: commit the merge with a message that names both sides' intents and the resolution rationale, including any discarded intent recorded in Step 4.54 - Rebase: `git rebase --continue` until every commit is replayed and no conflict remains.55 - Cherry-pick: `git cherry-pick --continue` (or commit, then continue if multiple commits remain).56 - 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.57 *Done when: `git status` shows no conflicts and the integration is complete.*5859## Failure and recovery6061| Failure class | Condition | Recovery |62|---|---|---|63| No conflict present | `git status` reports zero unmerged paths | Stop; trigger condition not met |64| 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 |65| Lockfile regeneration fails | Package manager cannot regenerate the lockfile | Do not hand-edit the lockfile; report the failure and leave it unresolved |66| Scoped check failure | A check introduced by the integration fails | Fix only integration-introduced failures; report pre-existing failures without suppression |67| Unresolved marker | Any `<<<<<<<` found after staging | Stop; report the path and line range |68| 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 |69| 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 |70| Non-convergence | Two resolution attempts produce the same check failure | Stop; report the conflict pair, both attempted resolutions, and the failure output |7172Partial-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.7374Rollback (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.7576## Output7778A 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.
OutlineDriven