Merge Conflict Resolution

Merge Conflict Resolution

Purpose

Prevent accidental loss of intended changes when a git merge or rebase hits conflicts (e.g., documentation regressions like the docs/architecture.md incident referenced in Feature 024).

This skill is intended for any agent that can commit changes.

Core Principle

A conflict is not a “choose ours/theirs” problem — it’s an intent reconciliation problem.

You must understand the intent of both changes before resolving anything. The correct resolution depends on intent, not on which side is main.

Often the right answer is “keep the intent of both changes”, which may require a manual edit that combines or restructures content.

Sometimes, intent is genuinely contradictory and cannot be resolved automatically. In that case, ask the user how to proceed.

Hard Rules

Must

• Analyze both sides first:
  • Identify what each side is trying to achieve (intent).
  • Identify which parts are compatible (can be merged) vs contradictory (need a decision).
• If the intent of either change is unclear, ask the user questions until it is clear. Do not guess.
• Resolve conflicts by editing the conflicted file(s) (not by blindly choosing one side).
• After resolution:
  • Verify that no conflict markers remain (<<<<<<<, =======, >>>>>>>).
  • Verify that git status shows no unmerged paths.
  • Validate that the resolved content preserves the intent of both changes (or reflects an explicit user decision when intent conflicts).

Must Not

• Blindly run git checkout --ours <file> / git checkout --theirs <file> without validating intent.
• “Resolve” by deleting sections just to make conflicts disappear.
• Commit a conflict resolution without reviewing the resulting diff.

When to Ask the Maintainer

If the conflict touches source-of-truth docs (e.g., docs/spec.md, docs/architecture.md) and the correct content is not unambiguous from the current task context, you must ask the maintainer which version to keep/merge before committing.

If the two change intents are contradictory (both cannot be true at the same time), you must ask the user to choose a direction. Do not attempt to “average” or invent a new intent.

Required Analysis (Before Editing)

Before you modify any conflicted file, produce an explicit analysis in chat using this template:

Conflict analysis

Change A intent:
- <what this change is trying to achieve>

Change B intent:
- <what this change is trying to achieve>

Compatibility:
- Compatible / Partially compatible / Contradictory
- Notes: <why>

Proposed resolution:
- <how you will preserve the intent of both changes>

Open questions (must answer before proceeding):
- <question 1>

If you cannot confidently state the intent for both changes, stop and ask.

Clarifying Questions (When Intent Is Unclear)

If you are in doubt about the intent of a change, ask questions until you understand it. Useful prompts:

• “Which behavior/statement should be true after this merge?”
• “Is this change a refactor (no behavior change) or a behavior change?”
• “Do we need to keep both changes, or should one override the other?”
• “If both changes cannot be kept, which one is more important and why?”
• “Is there a spec/issue/PR description that defines the intended outcome?”

Workflow (Recommended)

0. Confirm you are actually in a conflict

Use git to confirm the conflict state and list conflicted files:

git status
git diff --name-only --diff-filter=U

1. Identify conflicted files

git status
# or (machine-friendly)
git diff --name-only --diff-filter=U

2. Understand “ours” vs “theirs”

• During a merge:
  • “ours” = current branch (where you ran git merge ...)
  • “theirs” = the branch you’re merging in
• During a rebase:
  • “ours” / “theirs” semantics are different — prefer reading the conflict markers and using diffs rather than relying on naming.