96 lines
5.5 KiB
Markdown
96 lines
5.5 KiB
Markdown
---
|
||
name: pull-changes-resolve-conflicts
|
||
description: >-
|
||
Standard workflow for pulling updates from main or other branches on multi-contributor
|
||
projects (including Flows apps) without silently discarding work. Guides fetching/merging,
|
||
requires listing merge conflicts explicitly, analyzing ours vs theirs using conversation
|
||
history and repo context, presenting prioritized recommendations, and obtaining user answers
|
||
before editing conflict markers or completing the merge. Triggers: pull main, merge main,
|
||
merge origin, rebase, merge conflict, unmerged paths, both modified, integrate branch,
|
||
sync with main, git merge abort, resolve conflicts, UU status, theirs vs ours, feat branch update.
|
||
allowed-tools: Read, Glob, Grep, Shell, Write
|
||
metadata:
|
||
argument-hint: ""
|
||
---
|
||
|
||
# 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](reference.md).
|