agentleFS
iTwiniTwin/itwinjs-core/.github/skills/merge-conflict-resolving/SKILL.md

merge-conflict-resolving

Skill742 starsChanged 4 months agoMITView on GitHub

You resolve merge conflicts in code repositories, ensuring that the final merged code is functional and free of errors, and adheres to our code quality standards. Covers routine feature-branch merges from master, and modify/delete conflicts where a branch has deleted, split, or renamed a file that master still changes. For Mergify backport cherry-picks onto release/X.X.x, see the `backport-resolution` skill.

  • Deletes or force-pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 12 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    If they do conflict: Keep both files. If the same file has conflicts, merge the JSON content.

    line 52
  2. Very specific:

    Keep each entry once, as a ### heading under its ## section.

    line 68
  3. Distinctive:

    Do not blindly accept incoming — your branch may have different surrounding context

    line 88
  4. Distinctive:

    Not all conflicts come from Mergify.

    line 92
  5. Very specific:

    Verify before committing. Run the tests, not just the build — a ported test that compiles can still fail on a stale dependency.

    line 132
  6. Distinctive:

    Stop and summarize the port for the user before finishing the operation — see Review Gate.

    line 134
  7. Distinctive:

    Check the manifest against what is installed, then run the Rush update flow:

    line 142
  8. Distinctive:

    Identify conflict type: Run git status to see which files need resolution

    line 158
  9. Distinctive:

    Rush change files: Keep both / generate fresh → stage → commit

    line 163
  10. Very specific:

    Verify: Run rush build and ensure CI passes

    line 175
  11. Distinctive:

    Keep the resolution staged but unfinished while waiting.

    line 215
  12. Distinctive:

    Never offer git merge --abort during a cherry-pick or rebase — it does not apply to that state.

    line 223
  13. Distinctive:

    Only after approval, finish the operation and record in the message where the ported work went, so the next person does not think it was …

    line 225
  14. Distinctive:

    Exception: if the user has already stated they want the resolution completed without review, honor that.

    line 227
  15. Distinctive:

    If resolution goes wrong:

    line 231

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Merge Conflict Resolution

Resolve merge conflicts in this repository. Two situations produce them, and they need different recovery commands — identify which one you are in before touching anything:

SituationHow it arisesRecoveryStart here
BackportMergify cherry-picks a merged PR onto release/X.X.xgit cherry-pick --continue / --abortbackport-resolution skill
Feature branchYour branch merges master to stay currentgit merge --abortModify/delete conflicts

This skill is organized by file type (lock files, API reports, changelogs, source code) and applies to both. Backport-specific file types and rules — pnpm-config.json, package.json version precedence, NextVersion.md placement after a release, CI config, and anywhere the rule is "keep the release branch side" — live in the backport-resolution skill.

The highest-risk case is a modify/delete conflict: your branch deleted, split, or renamed a file that master then modified. Git offers "delete it" as a resolution, and taking it silently discards the incoming work with a clean build and green tests. That case has its own workflow and a mandatory review gate.

Lock Files (common/config/rush/pnpm-lock.yaml)

Always regenerate. Never manually edit.

rush update
# or for persistent issues:
rush update --full

Commit with: git commit -m "resolve pnpm-lock conflicts"

Examples: PR #8902, PR #8954

API Signature Files (common/api/*.api.md)

Always regenerate. Never manually edit.

These files track the public API surface and are generated by rush extract-api. They conflict when both branches have a different API surface.

rush build
rush extract-api

Also regenerate the export summary files: common/api/summary/*.exports.csv

Example: PR #8986 — backport of integrityCheck() modified common/api/core-backend.api.md

Rush Change Files (common/changes/@itwin/)

Rush change files are JSON files in common/changes/@itwin/<package>/ created by rush change. They usually have unique filenames and rarely conflict.

If they do conflict: Keep both files. If the same file has conflicts, merge the JSON content.

If change files are needed: Generate them non-interactively:

rush change --verify -b origin/<base-branch>
# If needed:
rush change --bulk --message "" --bump-type none -b origin/<base-branch>

Example: PR #8345 — had 30+ rush change files for a multi-package change

Documentation Conflicts (NextVersion.md)

NextVersion.md is the active changelog for the upcoming release. Resolve it to hold every entry from both sides:

  1. Keep each entry once, as a ### heading under its ## section. When both sides add the same section, the result is one section holding both sides' entries. List the allowed sections with node .github/workflows/automation-scripts/check-nextversion.mjs --sections.
  2. Rebuild the table of contents from the resulting headings.

Backports follow a different rule once the target release branch has shipped X.X.0 — NextVersion.md stays empty and entries move into X.X.0.md. See the backport-resolution skill.

Verification

node .github/workflows/automation-scripts/check-nextversion.mjs  # Sections, duplicates, table of contents
rush docs  # Ensure documentation builds

Source Code Conflicts (.ts files)

Possible whenever the same code area was modified on both branches.

Resolution:

  • Understand the intent of the incoming change
  • Apply the functional change to your branch's version of the code
  • Do not blindly accept incoming — your branch may have different surrounding context

Modify/Delete Conflicts on Refactored-Away Files

Not all conflicts come from Mergify. A long-lived feature branch that deletes or splits a file will conflict with every master commit that touches that file, and the conflict recurs on each merge until the branch lands.

CONFLICT (modify/delete): core/backend/src/test/imodel/IModel.test.ts
deleted in HEAD and modified in origin/master.

Never just re-delete the file. Git is telling you master added work that would be silently lost. The deletion is usually correct, but the incoming change must be ported to its new home first.

Workflow

  1. Identify exactly what master changed — do not read the whole file. Use the ref for the operation in progress (MERGE_HEAD for a merge, CHERRY_PICK_HEAD for a cherry-pick, REBASE_HEAD for a rebase):

    base=$(git merge-base HEAD MERGE_HEAD)
    git log --oneline $base..MERGE_HEAD -- <deleted-file>
    git show <commit> -- <deleted-file>
  2. Classify the incoming change by what kind of file it is, then port it:

    File kindIncoming changeAction
    Source (*.ts)New code addedPort into the module that now owns that responsibility; keep the exported names the incoming code expects
    Source (*.ts)Existing code modifiedApply the same edit to the migrated implementation
    Source (*.ts)Code removedRemove the migrated copy
    Public API surfaceAny of the aboveRe-run rush extract-api — a moved export changes common/api/*.api.md
    Docs / changelogEntry added or editedPort the entry into the file that replaced it (see NextVersion.md guidance above)
    Config / CISetting changedApply the setting to the file that now carries it; do not assume the old key name survived the split
    TestAdded, modified, removedPort into the test file that now owns that feature area — see the test-suite-refactoring skill
  3. Port faithfully, then adapt to the new file's conventions. Keep the behavior identical — only the surrounding plumbing (imports, helper names, module layout) should change. For ported tests specifically, keep the assertions identical and change only the fixture plumbing (shared fixtures, teardown helpers, tracker).
  4. Resolve the deletion and stage the port together:

    git rm <deleted-file>
    git add <file-that-received-the-port>
  5. Verify before committing. Run the tests, not just the build — a ported test that compiles can still fail on a stale dependency. If exported API moved, also run rush extract-api and inspect the regenerated report.
  6. Stop and summarize the port for the user before finishing the operation — see Review Gate. This is the one conflict type that requires review: the whole point is that work could have been silently dropped, and nothing in a green build would reveal it.
  7. Once approved, finish the operation (git commit for a merge, git cherry-pick --continue for a cherry-pick, git rebase --continue for a rebase) and record in the message where the change went, so the next person does not think it was dropped.

Incoming changes often carry dependency bumps

A ported test or module may depend on a native addon or package version bumped in the same master commit. The symptom is a confusing assertion failure rather than a dependency error — for example expected undefined to equal 2, because the older BisCore schema lacks a property the new test expects.

Check the manifest against what is installed, then run the Rush update flow:

git show <commit> -- core/backend/package.json   # did it bump @bentley/imodeljs-native?
rush update
rush build --to @itwin/core-backend

Avoid:

  • Re-deleting the file without inspecting the incoming diff — this silently drops master's work
  • Porting a test but leaving the accompanying dependency bump uninstalled
  • Assuming a clean build means the port is correct; tsc emits on type errors by default

Resolution Workflow

  1. Identify conflict type: Run git status to see which files need resolution
  2. Apply strategy:
    • Lock file: rush update → stage → commit
    • API files (common/api/): rush build → rush extract-api → stage → commit
    • Rush change files: Keep both / generate fresh → stage → commit
    • NextVersion.md: Merge both versions → stage → commit
    • Source code: Apply the incoming functional change to your branch's context → stage → commit
    • Modify/delete (file deleted on one side): Port the incoming change to its new home → stage → stop for review (see Review Gate)
    • Backport-specific files (pnpm-config.json, package.json, CI config): See the backport-resolution skill
  3. Check for residual conflict markers:

    grep -r "<<<<<<< " . --include="*.ts" --include="*.json" --include="*.md" --include="*.yaml" --include="*.yml"
  4. Verify: Run rush build and ensure CI passes
  5. Finish the operation — for every conflict type except modify/delete, complete it directly. If a modify/delete conflict was resolved, stop for review first (see Review Gate).

    • Merge: git commit using the messages below
    • Cherry-pick / rebase: git add the resolved files, then git cherry-pick --continue / git rebase --continue. Do not create a separate git commit first — the continue step would then be empty or duplicate the change

    Commit messages:

    • Lock files: "resolve pnpm-lock conflicts"
    • API files: "regenerate api files after merge"
    • Documentation: "merge NextVersion.md from both branches"
    • Multiple files: "resolve conflicts"

Completion Criteria

The resolution is done only when every box is checked:

  • git status reports no unmerged paths and no operation still in progress
  • grep -r "<<<<<<< " . returns nothing
  • rush build succeeds
  • Tests pass for every package touched by the resolution
  • rush extract-api produces no unexpected common/api/*.api.md changes
  • rush docs succeeds if any file under docs/ was resolved
  • Every modify/delete resolution was summarized and explicitly approved by the user
  • The final commit message records where any ported work went

Review Gate: Modify/Delete Conflicts Only

When a conflict is modify/delete — the file was deleted on one side and modified on the other — stop and ask the user to review before finishing the operation. Every other conflict type can be completed directly once verification passes.

This case alone gets a gate because its worst failure mode is invisible: the incoming change is silently dropped, and the result still builds and passes tests. A green verification run proves the code you kept is correct — it proves nothing about the code you discarded. For content conflicts both sides remain visible in the diff, so a reviewer can see what happened; for modify/delete, the discarded work leaves no trace.

Present a summary and wait for explicit approval:

  • Which operation is in progress — merge, cherry-pick (including a Mergify backport), or rebase; this determines the abort and finish commands below
  • What was deleted, and by which side
  • What the incoming side changed — the specific commits and what they added or modified
  • Where each change was ported — the new file and location that now owns it
  • What was dropped, if anything — call this out explicitly, even when dropping was clearly correct
  • Verification evidence — build, lint, and test results, including test counts before and after

Keep the resolution staged but unfinished while waiting. The tree stays inspectable, git diff --cached shows exactly what will land, and the abort for the operation in progress is still available:

Operation in progressAbortFinish after approval
Mergegit merge --abortgit commit
Cherry-pick (backports)git cherry-pick --abortgit cherry-pick --continue
Rebasegit rebase --abortgit rebase --continue

Never offer git merge --abort during a cherry-pick or rebase — it does not apply to that state. Confirm with git status, which names the operation in progress.

Only after approval, finish the operation and record in the message where the ported work went, so the next person does not think it was lost.

Exception: if the user has already stated they want the resolution completed without review, honor that. Otherwise, ask — including when the resolution looks trivial. A one-file deletion that quietly discarded a new test looks exactly like a one-file deletion that discarded nothing.

Rollback

If resolution goes wrong:

# Abort the operation in progress (check `git status` for which one)
git merge --abort
git rebase --abort
git cherry-pick --abort

# Or reset to the last good state (before the operation)
git reset --hard ORIG_HEAD
git clean -fd

# Then re-attempt
rush update

Quick Reference

File TypePathResolutionKey Points
Lock filecommon/config/rush/pnpm-lock.yamlrush updateNever manually edit
API signaturescommon/api/*.api.mdrush build + rush extract-apiNever manually edit
Rush change filescommon/changes/@itwin/*/Keep both or regenerateUsually unique filenames, rarely conflict
NextVersion.mddocs/changehistory/NextVersion.mdMerge both versionsBackports follow a different rule — see backport-resolution
Source code*.tsApply incoming intent to your branch's contextDo not blindly accept incoming
Refactored-away fileany (modify/delete)Port incoming change to its new home, then git rmNever re-delete blindly; stop for review before committing; check for accompanying dependency bumps

For Automated Agents

  • Check target branch first — Strategy differs for master vs release/X.X.x
  • Not every conflict is a backport — A feature branch merging master uses git merge; recovery is git merge --abort. Modify/delete conflicts here mean incoming work needs porting, not discarding
  • Backports use cherry-pick — Recovery is git cherry-pick --continue, and the release-branch rules live in the backport-resolution skill
  • Parse structured data — Extract version fields from package.json programmatically
  • Always check for conflict markers — grep -r "<<<<<<< " . before committing
  • Verify after resolution — Run rush build, rush extract-api, and check git diff
  • Never commit without testing — Ensure no syntax errors or breaking changes
  • Match the command to the operation — git status names it; abort with git merge --abort, git cherry-pick --abort, or git rebase --abort, and finish with git commit, git cherry-pick --continue, or git rebase --continue accordingly
  • Never commit a modify/delete resolution without user approval — Stage it, summarize what was ported and what was dropped, then wait. Tests cannot detect discarded work. All other conflict types can be committed directly once verification passes

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.