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 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.