Pull changes & resolve merge conflicts

Use this skill whenever integrating another branch (usually main) into the current feature branch, or when git status shows unmerged paths after a merge or rebase. Applies to any Git-based team workflow; Flows/React apps are a common case where conflicts cluster in app shells and shared libraries.

Goals

• Preserve intentional work on the current branch; do not assume “main wins” or “ours wins” without analysis.
• Make trade-offs visible to the user before any conflict resolution edits.
• Order discussion by impact: structural / feature / API / data-model changes before styling, copy, or spacing.

Hard rules

1. No silent resolution — Do not remove <<<<<<< / ======= / >>>>>>> or run git add on conflicted files until the user has agreed to the plan (or explicitly says “use your recommendations”).
2. Stop at conflicts — If a merge or rebase introduces conflicts, pause and report; do not bulldoze through large files by picking one side wholesale unless the user explicitly requests that.
3. Prioritize impact — When presenting conflicts, group and order roughly as:
   • P0 — Structural / product: removed routes, deleted modules, dropped features, changed data or API contracts, SDK or schema changes, auth or routing shell.
   • P1 — Behavior: logic, hooks, queries, filters, error handling, loading states.
   • P2 — UI structure: layout regions, new or removed sections, navigation.
   • P3 — Presentation: tokens, spacing, class names, copy tweaks.

Workflow

1. Fetch and integrate (or diagnose)

• Prefer git fetch then git merge origin/main (or the named branch) unless the user asked for rebase.
• If merge is already in progress, run git status and list every unmerged file.

2. Report conflicts to the user (explicit)

Output a clear list:

• Branch state: current branch, target branch (e.g. origin/main), merge vs rebase.
• Unmerged files: paths only, then optionally git diff --name-only --diff-filter=U.
• Per file (short): one line on what diverged (e.g. “AlertsPage — layout + new data scope”) if inferable from paths and git diff without resolving.

3. Analyze before editing

Use all of:

• Conversation history — What was the user or team trying to ship on this branch?
• Repo signals — Product or architecture docs if present (e.g. PRD.md), recent commits on the current branch, file ownership (e.g. large feature module vs shared lib/).
• Conflict hunks — git show :2:path (ours) vs git show :3:path (theirs) during merge, or read conflict markers; identify duplicated vs orthogonal changes.

Classify each conflicted area as:

• Orthogonal — safe to combine (e.g. import sort + new prop).
• Overlapping — must choose or manually merge (same lines).
• Corruption risk — duplicated blocks (common after bad merges); flag and recommend reconstructing from one side then re-applying the other side’s intent manually.

4. Recommendations + questions (required)

Present to the user:

1. Summary table or bullets — file → recommended side or “manual merge” → one-line why.
2. Ordered by P0 → P3 — call out anything that removes a feature or changes public behavior first.
3. Explicit questions — anything ambiguous (e.g. “Keep main’s global behavior or the branch’s scoped variant?”).
4. Ask for direction — e.g. “Reply with: (a) follow recommendations, (b) keep branch for file X, (c) keep main for file Y, (d) abort merge.”

Only after the user confirms (or gives a precise mapping), apply resolutions:

• Prefer small, surgical edits; preserve both sides’ intent when possible.
• Re-run git status; ensure no conflict markers remain; run tests or lint the user cares about for touched areas.

5. If the user wants to abort

• git merge --abort or git rebase --abort as appropriate; confirm they lose in-progress integration state for that operation.

Anti-patterns (do not do)

• Picking --ours / --theirs on the whole repo without user approval.
• “Resolving” by deleting a feature branch’s work because main touched the same file.
• Hiding conflict lists inside a long code dump without a short executive summary.
• Fixing low-impact style conflicts first while leaving P0 decisions implicit.

Quick reference

• Ours vs theirs (merge): stage 2 = current branch (HEAD), stage 3 = incoming (MERGE_HEAD). Verify with git checkout --conflict=merge <file> if needed.
• Typical high-touch paths in full-stack or Flows apps: root app shell, top navigation, route modules, and shared lib/ or hooks/.

For optional command snippets and a merge message template, see reference.md.