talent-factory/resolve-conflicts

Resolve Merge Conflicts

Analyse and resolve Git merge conflicts with semantic merging, automatic test validation, and a structured report. Uses strategy smart by default.

Parameters

| Parameter | Default | Description | |---|---|---| | [branch\|PR-number] | current branch | Branch to merge or PR number to resolve | | --target <branch> | develop | Target branch to merge from | | --dry-run | false | Analyse only — no file changes | | --no-tests | false | Skip test execution | | --strategy smart\|ours\|theirs | smart | Resolution strategy |

Workflow

Step 1 — Environment check

• Detect if running inside a git worktree (git worktree list)
• Check for uncommitted changes (git status --porcelain)
  • Halt if present — ask the user to commit or stash first
• Detect project type from existing files: pyproject.toml → Python; package.json → Frontend; pom.xml / build.gradle → Java

Step 2 — Parse input

• No argument → current branch, merge from --target
• Branch name → check out that branch
• PR number → resolve branch via gh pr view <N> --json headRefName -q .headRefName

Step 3 — Detect conflicts

git fetch origin
git merge-base HEAD origin/<target>
git merge --no-commit --no-ff origin/<target>

If no conflicts → abort merge, report "No conflicts found", done.

Collect conflicting files: git diff --name-only --diff-filter=U

Output a table: file | conflict type | risk level.

Step 4 — Analyse causes (per file)

For each conflict file:

1. git diff <merge-base>..HEAD -- <file> (our changes)
2. git diff <merge-base>..origin/<target> -- <file> (their changes)
3. Classify: content conflict · adjacent change · additive change · structural change
4. Identify source commit: git log --oneline <merge-base>..origin/<target> -- <file>

With --dry-run: abort merge here and display analysis report. Done.

Step 5 — Resolve (ordered simple → complex)

5a — Lock files (uv.lock, package-lock.json, bun.lockb):

git checkout --theirs <lock-file>
# Then regenerate:  uv lock  |  bun install  |  npm install

Halt if regeneration fails.

5b — Configuration files (pyproject.toml, package.json): Merge dependency lists as a union; remove duplicates; prefer higher version.

5c — Source code (depends on --strategy):

• smart: Merge import blocks as union; keep additive changes from both sides; for same-location edits, prioritise our logic and integrate their changes
• ours: git checkout --ours <file>
• theirs: git checkout --theirs <file>

5d — Alembic migrations: Linearise down_revision chain; create a merge migration if multiple heads result.

5e — Architectural conflicts (file fundamentally restructured): Halt and ask the user how to proceed. Show both versions. Continue only after explicit decision.

5f — Test files: Merge both suites; keep fixtures from both sides; ask on duplicate test names.

Step 6 — Syntactic validation (per resolved file)

grep -n "<<<<<<< \|======= \|>>>>>>> " <file>   # must be empty
python -c "import ast; ast.parse(open('<file>').read())"  # Python only

Re-analyse and re-resolve any file that still has markers or syntax errors.

Step 7 — Run tests (skip with --no-tests)

| Project type | Command | |---|---| | Python | uv run pytest | | Frontend | bun run test:run (or npm test) | | Java | mvn test (or ./gradlew test) |

If tests fail: attempt up to 2 repair cycles. After that, halt and report failing tests with full error output.

Step 8 — Linting

# Python
uv run ruff check . --fix && uv run ruff format .

# Frontend
bun run lint  (or npm run lint)

Step 9 — Report

Merge Conflict Report
=====================
Target:    origin/develop → feature/my-branch
Conflicts: N files
Strategy:  smart

File                     | Strategy     | Rationale              | Risk
-------------------------|--------------|------------------------|------
uv.lock                  | regenerated  | Lock file regenerated  | None
src/api/auth/__init__.py | smart/union  | Import lists merged    | Low
src/services/email.py    | smart/ours   | Logic conflict, manual | Med

Tests:  47 passed, 0 failed
Lint:   No errors

Step 10 — Commit and offer push

git add <resolved-files>
git commit -m "🔀 merge: Integrate <target> into <branch>

Resolved conflicts in N files:
- <file>: <brief rationale>
..."

Offer to push (git push origin <branch>) and wait for the user's confirmation.

Error Messages

| Situation | Message | |---|---| | Uncommitted changes present | Halt: "Please commit or stash your changes first." | | Merge already active | "A merge is already in progress. Continue (git merge --continue) or abort (git merge --abort)?" | | No remote branch | "Branch origin/<target> not found. Available: git branch -r" | | Lock regeneration failed | "Lock file regeneration failed. Run manually: uv lock / bun install" | | Tests failed after 2 attempts | Show failing test names, exit without committing |

Additional Resources

• ../references/resolve-conflicts/strategies.md — Strategy comparison and when to choose each
• ../references/resolve-conflicts/best-practices.md — Best practices for conflict-free branching
• ../references/resolve-conflicts/troubleshooting.md — Common failure modes and fixes