merge-resolve

Merge Resolve

Resolve merge conflicts by understanding both features' intent — not just the code diff.

Usage

/merge-resolve TICKET-1234                  # Resolve conflicts on TICKET-1234's PR
/merge-resolve TICKET-1234 --auto           # Resolve, push, and notify automatically

When This Runs

1. Factory PR can't merge — base branch has changed since PR was created
2. CI workflow detects conflict — auto-merge fails
3. Developer notices — PR shows merge conflicts on GitHub

Why This Is Better Than Manual Resolution

Traditional conflict resolution looks at code only — which lines overlap. This skill reads both features' story documentation to understand why each side made changes, then resolves based on intent:

• Method A was added for "invoice line item validation" (Story US-100)
• Method B was added for "batch processing of work orders" (Story US-200)
• Resolution: keep both methods — they serve different purposes

Step 1: Identify Conflicts

git fetch origin {{BASE_BRANCH}}

BRANCH="{TICKET_ID}"
git checkout "$BRANCH"
git merge origin/{{BASE_BRANCH}} --no-commit --no-ff 2>&1 | tee /tmp/merge-status.txt

# List conflicted files
git diff --name-only --diff-filter=U

If no conflicts → merge cleanly → done. Skip to Step 5.

Step 2: Understand Both Features

For each conflicted file, identify which tickets modified it:

MERGE_BASE=$(git merge-base HEAD origin/{{BASE_BRANCH}})
git log --oneline "$MERGE_BASE..origin/{{BASE_BRANCH}}" -- {conflicted_file}

For each ticket involved:

1. Read docs/stories/{OTHER_TICKET_ID}/story.md — understand the feature intent
2. Read docs/stories/{OTHER_TICKET_ID}/solutions-components.md — understand what was built
3. Read the current ticket's equivalent docs

This gives full context on why each side made its changes.

Step 3: Resolve Conflicts

Apply resolution rules based on file type and feature intent:

Resolution Rules by File Type

File Type	Strategy	Human Review?
Source code — different functions/methods	Keep both	No
Source code — same function modified	Merge logic based on story intent	Yes, if complex
Source code — imports/dependencies	Combine both sets	No
Configuration files	Union of both, deduplicate	No
Permission/access files	Union of both — never remove	No
Manifest/package files	Union of components, deduplicate	No
Schema/migration files	Keep both (may need ordering)	Yes
Flow/workflow files	Flag for review unless changes are in different elements	Yes
Test files	Keep both test cases	No
Test data factories/fixtures	Merge factory methods	No
UI components — same file	Merge based on feature intent	Yes, if complex
Story docs	No conflict (different ticket folders)	No