resolve-merge-conflicts
Skill3 starsChanged 13 days agoMITView on GitHub
Use when a merge, rebase, cherry-pick, or revert stops on conflicts, when a pull request is blocked by conflicts with its base, or when the user asks to resolve conflicts or bring a branch up to date with its base.
- Deletes or force-pushes
- Commits and pushes
13 other projects use a version of this.
Adopted by
Most recently taken up by
- warpdotdev/common-skillstheir own version, first seen Oct 20, 2026
- Ronnasayd/aipptheir own version, first seen Oct 20, 2026
- Ionate-Technologies/indium-agentkittheir own version, first seen Oct 20, 2026
- zhouycheng/skillstheir own version, first seen Oct 13, 2026
- nortonx/ai-tooling-freetheir own version, first seen Oct 13, 2026
- stealth-factory/skillstheir own version, first seen Oct 13, 2026
Used with
Projects with it also use diagnose-ci-failures, write-product-spec and 6 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
zerx-labSkilldiagnose-ci-failures
Diagnose CI failures for a PR using the GitHub CLI, extract error logs, and generate a plan to fix them. Use when the user asks to check CI status, pull CI issues, triage test failures, or investigate PR build failures.
Also in 3 projects that use this
zerx-labSkillwrite-product-spec
Write a PRODUCT.md spec for a significant user-facing feature in Zap, focused on detailed behavior and validation. Use when the user asks for a product spec, desired behavior doc, or PRD, wants to define feature behavior before implementation, or when the feature is substantial or behaviorally ambiguous enough that a written spec would improve implementation or review.
Also in 3 projects that use this
charlesmatteSkillwrite-tech-spec
Generate a technical specification document from an existing PRD through relentless technical interview and codebase exploration. Use when user wants to write a tech spec, technical specification, technical design document, TDD (technical design doc), or go deeper on the technical details of a PRD.
Also in 3 projects that use this
gitpod-ioSkillfix-errors
Guidelines for fixing unhandled errors from the VS Code error telemetry dashboard. Use when investigating error-telemetry issues with stack traces, error messages, and hit/user counts. Covers tracing data flow through call stacks, identifying producers of invalid data vs. consumers that crash, enriching error messages for telemetry diagnosis, and avoiding common anti-patterns like silently swallowing errors.
Also in 3 projects that use this
busybutlazySkillupdate-skill
Use this skill when the user wants to modify an existing public skill in this repository's canonical-skills, revise its workflow, or update its package metadata and version.
Also in 3 projects that use this
DockerSkillreview-pr
Review one or more incoming Docker documentation pull requests as a maintainer. Independently validate technical claims, assess editorial fit and information architecture, choose a verdict, and draft exact inline or PR-wide feedback behind a confirmation gate. Use for requests such as "review PR 123", "is this PR correct?", "does this information belong here?", "validate this PR", or "help review backlog PRs". Do not use to maintain or fix a PR you own; use maintain-pr for that.
Also in 3 projects that use this
- +2 more from zerx-lab
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- github/gh-aw★ 5.6ksame name
- zerx-lab/warp★ 2.1ksame name
- zerx-lab/zap★ 2.1ksame name
- warpdotdev/common-skills★ 630same name
- Indium-AI-Labs/indium-agentkit★ 18same name
- Ionate-Technologies/indium-agentkit★ 17same name
- stealth-factory/skills★ 5same name
- igorkulman/pi-skills★ 3same name
- khgouldy/skills★ 1same name
- nortonx/ai-tooling-free★ 1same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- comment-sweepSkill
- design-systemSkill
- domain-driven-designSkill
- feature-designSkill
- pr-babysitSkill
- pr-shipSkill
- test-driven-developmentSkill
- ux-brainstormSkill
- ux-stress-testSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Provenance: every line of the resolution serves one side's intent, or is glue that makes both hold (a renamed call, a moved import, an …
- Distinctive: line 47
Read both sides' PRs and issues.
- Distinctive: line 49
Write each intent down before editing:
- Very specific: line 59
Both can hold: write code that does what both meant, adapting one side to the other's structure.
- Distinctive: line 62
Every line keeps its provenance.
- Very specific: line 68
Run what CI runs, as far as it runs locally.
- Distinctive: line 92
When the conflict was a PR's, push: git push after a merge, git push --force-with-lease after a rebase.
- Distinctive: line 105
after a rebase, the starting SHA.
“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Resolve merge conflicts
A conflict is two changes that each had a reason. Git shows the lines; your job is to recover both reasons and write code that serves both. When they can't both hold, the landing side wins, and the report says what the other side loses.
- Sides: name each by what it is ("PR #42", "main") in everything you write. Git's ours is the checked-out branch during a merge, but the base being replayed onto during a rebase; theirs is the incoming branch, or the commit being replayed.
- Landing side: the change the user is trying to get in. It's the PR's branch when the base is merged into it or it is rebased onto the base, and the incoming branch when it is merged into the base. Its intent breaks ties.
- Intent: what a side meant to change about how the software behaves, and why, in one sentence with its source (PR, issue, ticket, test).
- Mechanical conflict: one whose hunk alone shows both intents, such as both sides adding an entry to the same list, an import, or a changelog line.
- Semantic conflict: two changes that merge without a marker and break together. One side renames a function; the other adds a call to the old name.
- Provenance: every line of the resolution serves one side's intent, or is glue that makes both hold (a renamed call, a moved import, an argument passed through). A merge commit is the one change nobody reviews, so a line without provenance lands unseen.
1. Start
git status names an operation already in progress (merge, rebase, cherry-pick, revert); if there is one, go to step 2. Otherwise git fetch and start it:
- Which operation: the one the user named. Without one, the repo's documented convention (CONTRIBUTING, AGENTS.md, CLAUDE.md). Without that, merge into a branch that's already pushed: a rebase rewrites commits others pulled or reviewed, and ends in a force-push, so it needs the user's or the repo's ask.
- Ancestor in every hunk: start it with
-c merge.conflictStyle=zdiff3(git -c merge.conflictStyle=zdiff3 merge origin/main, same forrebase). The ancestor is what both sides started from, the only way to tell who changed what. For an operation that already stopped,git checkout --conflict=zdiff3 -- <file>rewrites a file's markers, as long as you haven't edited it yet. - The user's checkout: with uncommitted changes or a different branch checked out, leave it exactly as it is. Work in
git worktree add --detach ../<repo>-conflicts origin/<branch>, push withgit push origin HEAD:<branch>, and remove the worktree at the end.
Record git rev-parse HEAD before starting: it's how the user gets back.
Done when the operation has stopped on conflicts, or has finished without any. In that case go to step 5, since semantic conflicts still need the checks.
2. List
git diff --name-only --diff-filter=U lists the conflicted files. Lockfiles, generated files, binaries, and files one side deleted or renamed need handling of their own: when any is in the list, read references/special-files.md.
Then list the files both sides changed since the merge base (git diff --name-only <merge-base>...<side> for each side, intersected). That's where semantic conflicts hide.
Done when every conflicted file is either a content conflict or handled per special-files.md, and you hold the both-sides list.
3. Recover intent
For every hunk that isn't mechanical, work out each side's intent from the evidence around the diff. A hunk that looks like a typo fix can be a security fix; one that looks like a refactor can change behavior on purpose.
- Commits:
git log --merge -p -- <file>lists both sides' commits that touched the file since the merge base, during any of the four operations. During a rebase,git show REBASE_HEADis the commit being replayed. - Pull requests: each commit's PR (
gh api repos/{owner}/{repo}/commits/<sha>/pulls), then its title, body, and review discussion (gh pr view <n> --json title,body,comments,reviews,closingIssuesReferences). - Issues and tickets: the issues the PR closes or links, and ticket keys in commit messages, PR titles, and branch names (
ENG-123), through the tracker's CLI or MCP. The ticket usually holds the why. - Tests and callers: the tests each side added or changed are the most precise statement of intent there is.
Read both sides' PRs and issues. The side you're not on is the one whose reasons you don't already know. Look up each commit and PR once, however many hunks it touches.
Write each intent down before editing:
src/cart.jslineTotal: PR #42 (closes #40) applies the discount to each line, because per-order rounding drifted from the invoice. main, from PR #45 (fixes #44), rejects quantities below 1, because a negative quantity produced a refund.
Done when every non-mechanical hunk has both sides' intent written with its source. If a side's intent can't be recovered (no PR, a one-word message, no ticket, no test), note that instead and read the intent from the code as narrowly as you can.
4. Resolve
Hunk by hunk, from the intents:
- Both can hold: write code that does what both meant, adapting one side to the other's structure. If main renamed
calcTotaltolineTotaland the PR added a branch tocalcTotal, the branch goes intolineTotal. Keep both sides' tests. - They can't both hold (one behavior, changed two ways): take the landing side. Change the other side's tests only where they assert the behavior you dropped, and name the loss in the report. When the side you'd drop fixes a security hole or data loss, ask the user before dropping it.
Every line keeps its provenance. A bug or improvement you notice along the way goes in the report, as a change of its own.
git add each file as it's done. Done when git diff --name-only --diff-filter=U is empty and git diff --cached --check finds no leftover markers.
5. Check
Run what CI runs, as far as it runs locally. Its config (.github/workflows/ or the repo's equivalent) names the commands, typically install, typecheck, lint, tests, and build. Run the full set: a semantic conflict breaks files that neither side's hunks touched.
- Caused by the resolution: fix it and rerun.
- A semantic conflict: resolve it like step 4, from the intents, and report it.
- Also fails on the base (run the same command on the base, in a worktree): it isn't yours; report it.
During a rebase, run the fast checks (typecheck or build, and the tests of the files you touched) at each stop, then the full set once the rebase finishes.
Done when every check passes, or fails identically on the base.
6. Verify the app
When the conflicting code changes what a user sees or does and the project runs locally (dev server, CLI, simulator), start it with the harness's run or preview tool or the documented start command. Exercise both sides' behavior: the landing side's feature, and the base change it was combined with.
Done when you've seen both behaviors work, or can name what you couldn't run and why (secrets, services, hardware).
7. Finish
- Merge:
git commit --no-edit, adding a body line for each non-mechanical hunk: what was combined or dropped, and why. - Rebase:
GIT_EDITOR=true git rebase --continuekeeps each commit's message. Repeat steps 2–5 at every stop until git reports the rebase done, so every commit is replayed with its resolution.git rebase --skipwould drop the commit's other changes along with its conflict. - Cherry-pick or revert:
--continue, the same way.
Confirm that nothing was lost. After a rebase, git log --oneline <base>..HEAD should list as many commits as before, less any that git dropped as already upstream (it names them). After a merge, git log -1 --format=%P should show two parents.
When the conflict was a PR's, push: git push after a merge, git push --force-with-lease after a rebase. A local merge or rebase the user asked for stays local.
Done when no operation is in progress and the result is either pushed or deliberately left local.
8. Report
For each non-mechanical conflict, give the file, each side's intent with its source (as links), and the resolution: combined, or the side taken and what the other loses. Cover all mechanical conflicts in one line. Then list:
- the semantic conflicts found;
- the checks run, with their results;
- what you exercised in the app;
- anything you couldn't recover or verify;
- bugs you noticed that are out of scope;
- after a rebase, the starting SHA.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

