Resolve Merge Conflicts

Resolve Merge Conflicts

Use this skill when a user wants merge conflicts on an active PR resolved all the way through, not just inspected.

The goal is:

• identify the PR base branch
• merge the base into the current branch locally
• resolve the conflicted files without discarding intentional branch work
• validate the merged result
• commit the merge
• push the updated branch

Preconditions

• the current branch should already be the PR branch you intend to update
• gh should be authenticated for the repo if you need to inspect PR metadata
• do not assume a conflict is already present locally; check first

Workflow

1. Inspect the current branch and PR context.

Start with:

git status --short --branch
git diff --name-only --diff-filter=U
gh pr view --json number,title,baseRefName,headRefName,url

Notes:

• if git diff --name-only --diff-filter=U is empty, there may be no active conflicted merge in the worktree yet
• if needed, verify the branch matches headRefName from the PR

2. Fetch the latest base branch state.

Typical command:

git fetch origin

3. Merge the PR base branch into the current branch locally.

Typical command:

git merge --no-edit origin/<base-branch>

Examples:

git merge --no-edit origin/main
git merge --no-edit origin/develop

If the merge reports conflicts, capture the conflicted files:

git diff --name-only --diff-filter=U

4. Read each conflicted file before editing.

Look for conflict markers:

rg -n "^(<<<<<<<|=======|>>>>>>>)" <file>

Guidance:

• keep the current branch's feature intent intact
• absorb compatible changes from the base branch
• prefer the newer shared API or wiring from base when it does not invalidate the feature branch's design
• remove conflict markers completely
• do not blindly take one side for large files; reconcile the behavior

5. Resolve the conflicts carefully.

When reconciling:

• preserve branch-specific feature work
• preserve legitimate upstream fixes from base
• adapt old single-file assumptions if the branch has moved to package-level or directory-level behavior
• update tests when upstream added coverage that still assumes old shapes

After edits, verify there are no remaining conflict markers:

rg -n "^(<<<<<<<|=======|>>>>>>>)" src

6. Run the smallest useful validation for the merged surfaces.

Recommended baseline:

pnpm typecheck

Then add focused tests for the files or systems touched by the conflict resolution. Examples:

pnpm exec vitest run src/main/issue-resolution.test.ts
pnpm exec vitest run src/main/skill-inventory.test.ts
pnpm exec vitest run src/renderer/src/views/InventoryViewChrome.test.tsx

If the conflict changes visible UI, also run a real browser check with Playwright.

7. Stage the resolved files and complete the merge commit.

Typical flow:

git add <resolved-files>
git status
git commit --no-edit

Notes:

• during a merge, git commit --no-edit will usually finish the merge commit using the default merge message
• only use a custom commit message if there is a clear reason

8. Push the updated PR branch.

Typical command:

git push origin <current-branch>

Example:

git push origin codex/skills-are-directories-not-files

9. Report back clearly.

Include:

• which files had conflicts
• the core reconciliation decisions
• the exact validation you ran
• whether the branch was pushed successfully

Decision Standards

• Do not throw away either side without understanding what behavior it carried.
• Prefer the feature branch's architectural direction when that is the purpose of the PR.
• Prefer the base branch's new shared APIs, tests, and wiring when they can be integrated cleanly.
• If upstream changed assumptions that conflict with the PR's design, reconcile the newer code to the PR's model instead of silently reverting the feature.
• Keep the result coherent; conflict resolution is integration work, not line-level arbitration.

Common Pitfalls

• assuming conflicts already exist locally when they do not
• resolving only the compile errors and missing test expectation drift
• leaving one file still marked UU because it was edited but not staged
• forgetting that merge commits are still in progress until git commit
• pushing before re-running targeted validation

Final Response To The User

Report back with:

• what conflicted
• what you chose in the reconciliation
• what checks passed
• confirmation that the branch was pushed