fix-conflicts

Fix Conflicts

Announce: "I'm using the fix-conflicts skill to resolve merge conflicts."

Step 1: Detect Conflict State

Run the conflict state detector:

./scripts/get-conflict-state.sh

The output shows the operation type (merge, rebase, revert, cherry-pick), conflicted files with their conflict types, and branch context.

If Operation is "none" and no conflicted files: inform the user there are no conflicts to resolve and stop.

If the user's invocation prompt specifies a file: limit resolution scope to that file only (verify it appears in the conflicted list).

Step 2: Read Conflicted Files

Read every conflicted file listed in Step 1. For large files (>500 lines), focus on sections containing conflict markers (<<<<<<<, =======, >>>>>>>).

Then gather history context to understand what each side intended:

# Local commits that touched conflicted files
./scripts/get-conflict-history.sh local

# Remote commits that touched conflicted files
./scripts/get-conflict-history.sh remote

For each commit listed in the history output, inspect its actual diff to understand intent:

# Show the full diff for a specific commit touching the conflicted file
git show <commit-sha> -- <conflicted-file>

Pay attention to:

• Additions: new code, new functions, new parameters
• Removals: deleted code, removed functions, removed parameters — note whether the commit message explains the removal (refactor, deprecation, cleanup) or whether the removal looks incidental to a larger change
• Modifications: changed logic, renamed symbols, updated signatures

For each conflict, determine:

Step 3: Resolve by Conflict Type

Rebase conflict orientation (CRITICAL)

During git rebase, ours/theirs are reversed from merge:

The code between ======= and >>>>>>> is YOUR feature branch work. Never discard it without explicit user confirmation — doing so silently loses changes you wrote.

Resolution posture during rebase:

1. Treat the theirs section as the change you must land; treat the ours section as context to integrate around it.
2. If both sides modified the same lines with incompatible intent, ask the user (see "When uncertain" below).
3. "Upstream looks newer/cleaner" is NOT sufficient justification to drop theirs.

Standard conflicts (UU — both modified, AA — both added)

1. Understand intent of both sides from history and surrounding code.
2. Choose resolution strategy:

3. Remove ALL conflict markers (<<<<<<<, =======, >>>>>>>).
4. Verify the result is syntactically correct.

Intent preservation rules (apply to ALL conflict types)

Before writing the resolved version of any conflict, complete this checklist:

1. List both sides' meaningful changes. For each side, write a one-line summary of what it intended (from Step 2's git show analysis).
2. Verify no silent drops. If you are keeping only one side's text, confirm the other side made no substantive changes (logic, behavior, API) in that region. Formatting-only or whitespace-only differences are safe to drop.
3. Respect intentional removals. If one side removed code that the other side still has (or modified):
   • git show the commit that performed the removal.
   • If the commit message or diff shows a deliberate action (refactor, deprecation, dead-code cleanup, feature removal), do not re-add the removed code — the removal wins.
   • If the removal looks incidental (part of a large unrelated change, no mention in the commit message), ask the user whether the removal was intentional.
4. Never re-add intentionally deleted code. Code that was removed in a dedicated cleanup or refactor commit must stay removed, even if the other side's conflict block still contains it.

Wholesale side selection guardrails

Taking an entire side (--ours / --theirs or keeping one conflict block verbatim) is only safe when the other side's changes in that region are trivially reconcilable.

Before selecting a whole side, run git show <commit> -- <file> for the side you would drop and confirm its changes are present elsewhere or are not meaningful.

Modify/delete conflicts (UD — modified locally/deleted remotely, DU — deleted locally/modified remotely)

1. Identify which side deleted and which modified.
2. Inspect the deletion commit to determine intent:

# Find the commit that deleted the file on the deleting side
git log --diff-filter=D --oneline -1 -- <file>

# Examine the commit to understand why
git show <deletion-commit-sha>

3. Classify the deletion:

4. If still uncertain, ask the user:

Pause and ask the user. Wait for their answer before proceeding.

Keep or delete? -- <file> was modified on one side but deleted on the other. The modification: <brief description>. The deletion was in commit <sha>: <message>. The deletion appears <intentional|incidental>. Keep the modified version or delete?

• Keep modified -- Stage the modified version with git add
• Delete -- Stage deletion with git rm

Add conflicts (AU — added by us, UA — added by them)

1. Review the added file's content and purpose.
2. If keeping: git add <file>
3. If removing: git rm <file>
4. If both sides added with different content: treat as a standard UU conflict.

When uncertain about any conflict

Do NOT guess about business logic. Ask the user.

For merge conflicts:

Pause and ask the user. Wait for their answer before proceeding.

Conflict choice -- Conflict in <file>: <brief description of both sides>. How should this be resolved?

• Keep local (ours) -- Use the local/HEAD version
• Keep remote (theirs) -- Use the incoming version
• Merge both -- Combine changes from both sides
• Leave unresolved -- Skip this file for manual resolution

For rebase conflicts (ours = upstream, theirs = your feature branch):

Pause and ask the user. Wait for their answer before proceeding.

Conflict choice (rebase) -- Conflict in <file> while replaying your commit '<commit message>'. Upstream (HEAD) has: <ours summary>. Your branch has: <theirs summary>. How should this be resolved?

• Keep your branch change (theirs) -- Preserve your feature branch work
• Keep upstream (ours) -- Discard your branch's version for this section
• Merge both -- Combine both sides
• Leave unresolved -- Skip this file for manual resolution

Version and changelog conflicts

When a version field or changelog conflicts, the upstream (main) side has released a new version. NEVER merge version entries. The upstream release history is immutable.

Resolution rule: Keep all upstream version entries and release notes exactly as they are. Bump your version to be strictly above the upstream version, then add your changelog entry as the newest.

Content truncated.