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 scripts/git-status.sh 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:

scripts/git-status.sh
git diff --name-only --diff-filter=U

1. Identify conflicted files

scripts/git-status.sh
# 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.

3. Inspect what each side changed

For each conflicted file:

# See conflict hunks and surrounding context
sed -n '1,200p' <file>

# Compare current index stages (2=ours, 3=theirs) if available
# (These commands are safe even if a stage is missing.)
git show :2:<file> 2>/dev/null | head -50 || true
git show :3:<file> 2>/dev/null | head -50 || true

While inspecting, explicitly determine intent:

What was added/removed/renamed, and why?
Is one side a refactor and the other a feature? If yes, the resolution often needs both.
Are there invariants that must remain true (docs accuracy, API behavior, tests)?

4. Resolve conflicts intentionally

Edit the file to combine the correct parts from both sides.
Remove conflict markers.
Preserve required sections (especially for documentation).

5. Verify resolution quality

# Review what you’re about to commit
scripts/git-diff.sh

# Ensure git sees conflicts as resolved
scripts/git-status.sh

Also do a repo-wide check that no conflict markers remain. Prefer tooling that searches files directly (no scripts required), for example:

VS Code Search panel: search for <<<<<<< , =======, and >>>>>>>
If you are operating as a Copilot agent: use the workspace text-search tool to search for <<<<<<<, =======, and >>>>>>>
Optional fallback (terminal): git grep -n '^<<<<<<< ' || true (repeat for the other markers)

6. Validate the meaning, not just the markers

After conflicts are resolved, validate correctness based on file type:

Documentation changes:
- Ensure the resulting documentation captures the intent of both changes and no relevant information is lost.
- Ensure the docs do not contain contradictory statements introduced by the merge.
- Check for common merge-regressions:
  - Deleted or duplicated headings/sections
  - Outdated statements reintroduced
  - Partial merges where one side’s detail vanished
- If there are contradictions, resolve them explicitly or ask the user which statement is correct.
Code changes:
- Ensure all tests pass.
- Ensure the intended new features or behavior changes of both changes still work.
- If tests exist for the changed area, run those first; then broaden if needed.

7. Continue or conclude

If this is a merge:
```
git add <file>...
git commit
```

If this is a rebase:

git add <file>...
git rebase --continue

Commit Message Requirement (For Merge Conflict Resolutions)

When you create a commit that resolves conflicts, the commit message must describe:

Which files had conflicts (high level)
How the conflict was resolved (e.g., “combined both intents”, “kept X and adapted Y to match”, “user chose A over B”)
Why this resolution preserves the intended behavior/documentation

Template:

<type>: resolve merge conflicts

Conflicts:
- <file/group>: <what conflicted>

Resolution:
- <how you preserved intent of both changes OR what decision was made>

Why:
- <why this is correct>

Notes

If you get stuck, prefer asking for guidance over guessing. A wrong conflict resolution can silently ship broken docs.

merge-conflict-resolution