Resolve Conflicts

Git Conflict Resolution

Resolve Git merge conflicts by intelligently combining changes from both branches while preserving the intent of both changes. This skill follows a plan-first approach: assess conflicts, create a detailed resolution plan, get approval, then execute.

Core Principles

1. Plan Before Executing: Always create a structured resolution plan and get user approval before making changes
2. Prefer Both Changes: Default to keeping both changes unless they directly contradict
3. Merge, Don't Choose: Especially for imports, tests, and configuration
4. Regenerate Generated Files: Never manually merge generated files - always regenerate them from their sources
5. Backup Before Resolving: For deleted-modified files, create backups first
6. Validate with Tests: Always run tests after resolution
7. Explain All Resolutions: For each conflict resolved, provide a one-line explanation of the resolution strategy
8. Ask When Unclear: When the correct resolution isn't clear from the diff, present options to the user and ask for their choice

Workflow

Step 1: Assess the Conflict Situation

Run initial checks to understand the conflict scope:

git status

Identify and categorize all conflicted files:

• Regular file conflicts (both modified)
• Deleted-modified conflicts (one deleted, one modified)
• Generated file conflicts (lock files, build artifacts, generated code)
• Test file conflicts
• Import/configuration conflicts
• Binary file conflicts

For each conflicted file, gather information:

• File type and purpose
• Nature of the conflict (content, deletion, type change)
• Scope of changes (lines changed, sections affected)
• Whether the file is generated or hand-written

Step 2: Create Merge Resolution Plan

Based on the assessment, create a structured plan before resolving any conflicts. Present the plan in the following markdown format:

## Merge Resolution Plan

### Conflict Summary

- **Total conflicted files**: [N]
- **Deleted-modified conflicts**: [N]
- **Generated files**: [N]
- **Regular conflicts**: [N]

### Resolution Strategy by File

#### 1. [File Path]

**Conflict Type**: [deleted-modified / generated / imports / tests / code logic / config / struct / binary]
**Strategy**: [Brief description of resolution approach]
**Rationale**: [Why this strategy is appropriate]
**Risk**: [Low/Medium/High] - [Brief risk description]
**Action Items**:

- [ ] [Specific action 1]
- [ ] [Specific action 2]

#### 2. [File Path]

...

### Execution Order

1. **Phase 1: Deleted-Modified Files** - Handle deletions and backups first
2. **Phase 2: Generated Files** - Regenerate from source
3. **Phase 3: Low-Risk Merges** - Imports, tests, documentation
4. **Phase 4: High-Risk Merges** - Code logic, configuration, structs
5. **Phase 5: Validation** - Compile, test, verify

### Questions/Decisions Needed

- [ ] **[File/Decision]**: [Question for user] (Options: 1, 2, 3)

### Validation Steps

- [ ] Run conflict validation script
- [ ] Compile project
- [ ] Run test suite
- [ ] Manual verification of high-risk changes

Present this plan to the user and wait for their approval before proceeding with resolution. If there are any unclear conflicts where you need user input, list them in the "Questions/Decisions Needed" section.

For a complete example plan, see references/sample-plan.md.

Step 3: Handle Deleted-Modified Files

Execute this phase only after the plan is approved.

If there are deleted-but-modified files (status: DU, UD, DD, UA, AU):

.forge/skills/resolve-conflicts/scripts/handle-deleted-modified.sh

This script will:

• Create timestamped backups of modified content
• Analyze potential relocation targets
• Generate analysis reports for each file
• Automatically resolve the deletion status

Review the backup directory and analysis files to understand where changes should be applied.

Step 4: Execute Resolution Plan

Follow the execution order defined in your plan. For each conflicted file, apply the appropriate resolution pattern according to your plan. For every conflict you resolve, provide a one-line explanation of how you're resolving it.

As you complete each action item in your plan, mark it as done and report progress to the user.

When Resolution is Unclear

When you cannot determine the correct resolution from the diff alone (these should already be listed in your plan's "Questions/Decisions Needed" section):

1. Present the conflict to the user with the conflicting code from both sides
2. Provide numbered options for resolution (Option 1, Option 2, etc.)
3. Explain each option clearly with what it would do
4. Ask the user to choose an option number or provide additional information
5. Remember their choice and apply similar reasoning to subsequent related conflicts

Example interaction:

I found a conflict in src/main.rs where both branches modify the `calculate_price` function:

<<<<<<< HEAD (Current Branch)
fn calculate_price(item: &Item) -> f64 {
    item.base_price * (1.0 + item.tax_rate)
}
=======
fn calculate_price(item: &Item) -> f64 {
    item.base_price + item.tax_amount
}
>>>>>>> feature-branch (Incoming Branch)

I'm not sure which calculation is correct. Please select an option:

**Option 1**: Keep current branch (multiplies base_price by tax_rate)
**Option 2**: Keep incoming branch (adds tax_amount to base_price)
**Option 3**: Keep both approaches with a new parameter
**Option 4**: Provide more context to help me decide

Please respond with "Option 1", "Option 2", "Option 3", or "Option 4", or provide additional information.

Once the user responds, apply their decision and similar logic to related conflicts.

Resolution Patterns

For each conflicted file, apply the appropriate resolution pattern:

Imports/Dependencies

Goal: Merge all unique imports from both branches.

One-line explanation: "Merging imports by combining unique imports from both branches, removing duplicates, and grouping by module."

Read references/patterns.md section "Import Conflicts" for detailed examples.

Quick approach:

1. Extract all imports from both sides
2. Remove duplicates
3. Group by module/package
4. Follow language-specific style (alphabetize, group std/external/internal)

Tests

Goal: Include all test cases and test data from both branches.

One-line explanation: "Merging tests by including all test cases from both branches, combining fixtures, and renaming if necessary to avoid conflicts."

Read references/patterns.md section "Test Conflicts" for detailed examples.

Quick approach:

1. Keep all test functions unless they test the exact same thing
2. Merge test fixtures and setup functions
3. Combine assertions from both sides
4. If test names conflict but test different behaviors, rename to clarify

Generated Files

Goal: Regenerate any generated files to include changes from both branches.

One-line explanation: "Resolving generated file by regenerating it from source files to incorporate changes from both branches."

Recognition: A file is generated if it:

• Is produced by a build tool, compiler, or code generator
• Has a source file or configuration that defines it
• Contains headers/comments indicating it's auto-generated
• Is listed in .gitattributes as generated
• Common examples: lock files, protobuf outputs, GraphQL schema files, compiled assets, auto-generated docs

Approach:

1. Identify the generation source: Determine what command or tool generates the file
2. Choose either version temporarily (doesn't matter which):

   git checkout --ours <generated-file>    # or --theirs

1. Regenerate from source: Run the appropriate generation command:

   # Package manager lock files
   cargo update                       # for Cargo.lock