Merge Conflict Architect

Overview

Use this skill to perform intelligent, low-risk Git merge conflict resolution.

The primary objective is not simply to remove conflict markers but to preserve the intent of both branches while minimizing the risk of regressions, accidental deletions, and lost work.

This skill behaves like an experienced engineer performing a careful manual merge.

Core Philosophy

Principle 1: Preserve Unrelated Work

The highest priority is preserving all changes that are unrelated to the conflict.

Never:

• Revert unrelated modifications.
• Remove existing functionality.
• Rewrite surrounding code unnecessarily.
• Reformat large sections of code.
• Introduce broad changes outside the conflict area.

Only modify code that is directly required to resolve the conflict.

Principle 2: Understand Both Sides

Before resolving a conflict, determine:

• Why the source branch changed.
• Why the target branch changed.
• Whether changes are complementary.
• Whether changes are mutually exclusive.
• Whether both changes should coexist.

Never automatically favor one side. Always understand intent first.

Principle 3: Prefer Preservation Over Deletion

When uncertain, prefer preserving behavior rather than removing it. Generally:

• Keep functionality from both branches.
• Merge implementations when compatible.
• Preserve validations, safeguards, and error handling.
• Preserve tests.

Deleting code requires justification.

Principle 4: Resolve the Smallest Possible Surface Area

Only change what is necessary. Avoid refactoring, renaming, moving code, or architectural changes during conflict resolution. Conflict resolution is not refactoring.

Principle 5: Ask When Confidence Is Low

If multiple valid resolutions exist and intent cannot be confidently determined, stop and ask the user. Do not guess when business logic differs significantly, APIs changed incompatibly, data models conflict, architectural direction is unclear, or either branch appears incomplete.

Conflict Resolution Strategy

Step 1: Identify Conflict Scope

Determine the files affected, conflict regions, branches involved, and type of conflict. Classify conflicts as text, logic, API, dependency, type, configuration, or test conflicts.

Step 2: Understand Branch Intent

For each side, determine what was changed, why it was changed, and what problem it solves. Do not begin resolution until intent is understood.

Step 3: Compare Behavioral Impact

Evaluate added functionality, removed functionality, changed behavior, new validations, new dependencies, API changes, and state changes. Determine whether both behaviors should exist, one supersedes another, or a hybrid is required.

Step 4: Choose Resolution Strategy

• Combine both changes when they are compatible and additive. Preferred.
• Adopt the newer implementation when one branch clearly replaces another.
• Preserve existing behavior when the incoming change introduces risk.
• Escalate to the user when intent is unclear or data integrity is at stake.

Special Handling Rules

Never remove code without verifying no callers, tests, or workflows depend on it and that equivalent behavior exists elsewhere.

Never accidentally remove validation logic, permission checks, error handling, retry logic, loading states, cleanup logic, event listeners, or feature flags.

Prefer keeping tests from both branches. When tests conflict, update them to reflect merged behavior. Never remove tests solely to make the merge pass.

Never weaken typing to resolve conflicts. Avoid adding any, removing type checks, removing null handling, or removing runtime guards.

Risk Analysis

For every resolution, check for regressions (does existing behavior change or break), compatibility (do APIs, types, and consumers stay compatible), and dependencies (are any added, removed, or version-mismatched).

Resolution Output Requirements

After every merge resolution, provide:

• Conflict summary: files affected, conflicts resolved, strategy used.
• Accepted changes from each branch.
• Removed changes, with an explanation of why.
• Combined changes and the rationale for any hybrid implementation.
• Potential risks and areas needing regression testing.
• A targeted test plan for modified behavior, critical workflows, edge cases, and integration points.

Review Checklist

• All conflict markers removed.
• No unrelated code modified.
• Existing and new functionality preserved.
• Tests updated if required.
• Types remain valid.
• No accidental deletions or hidden regressions.
• Resolution rationale documented and a merge summary generated.

Anti-Patterns to Avoid

• Blindly choosing Accept Current or Accept Incoming.
• Resolving conflicts without understanding intent.
• Removing code to simplify resolution.
• Refactoring during merge resolution.
• Weakening types to make code compile.
• Removing tests instead of updating them.
• Overwriting unrelated changes or assuming intent when it is unclear.

Final Objective

Resolve merge conflicts with the same care as a senior engineer performing a production-critical merge: preserve unrelated work, minimize risk, avoid accidental deletions, maintain compatibility, and provide a transparent audit trail of every resolution decision.