/resolve-pr-conflicts

Overview

Resolve pull request merge conflicts without merging into main. Work on the PR branch or a maintainer-owned conflict-fix branch, commit the resolved files, push the branch, and leave the PR open for user testing.

Workflow

1. Identify the PR

Use the PR number or URL if the user provides one. Otherwise inspect open PRs and choose the newest conflicted PR, clearly saying that assumption.

Prefer GitHub connector tools when available. Otherwise use gh:

gh pr list --state open --limit 20 \
  --json number,title,author,headRefName,headRepositoryOwner,baseRefName,mergeStateStatus,isCrossRepository,url,updatedAt
gh pr view <number> \
  --json number,title,body,author,headRefName,headRepositoryOwner,baseRefName,mergeStateStatus,isCrossRepository,maintainerCanModify,url,files,statusCheckRollup

Record the PR URL, base branch, source branch, whether the PR is from a fork, whether maintainers can modify it, and the current check state.

2. Protect Local Work

Check the current checkout before changing branches:

git status --short --branch
git worktree list

Do not overwrite or revert unrelated local changes. Prefer a new worktree for conflict work, especially when the main checkout has local files.

Use a worktree from the PR branch when it can be pushed:

git fetch origin <base-branch>
gh pr checkout <number> --branch <local-pr-branch>
git worktree add ../<repo>-pr-<number>-conflicts <local-pr-branch>

If the PR comes from a fork and cannot be pushed safely, create a same-repo branch from the PR head instead and tell the user the original PR may need a replacement PR:

gh pr checkout <number> --detach
git switch -c <maintainer-conflict-branch>

3. Bring in the Base Branch

Fetch the latest base branch and merge it into the PR branch. Do not merge the PR into main.

git fetch origin <base-branch>
git merge origin/<base-branch>

If the repository convention prefers rebase and the PR has not been shared or reviewed, rebase is acceptable. For existing shared PRs, prefer merge because it does not rewrite the contributor's history.

4. Resolve Conflicts Deliberately

List conflicted files:

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

For each file:

• Read both sides of the conflict and the surrounding current code.
• Keep the intended PR behavior while preserving newer changes from the base branch.
• Remove all conflict markers: <<<<<<<, =======, >>>>>>>.
• Avoid broad formatting or unrelated cleanup while resolving conflicts.
• Regenerate derived files only when the repository has an established generator for the affected output.

Use structured tools for structured formats where practical:

• YAML: preserve indentation, anchors, substitutions, and comments.
• JSON/package lock files: prefer the package manager or lockfile-aware tooling.
• Generated firmware, manifests, icons, or docs output: run the matching generator/check command instead of hand-editing large generated sections.

When the right resolution is unclear, inspect the original PR diff and recent base-branch changes:

gh pr diff <number> --patch
git log --oneline --decorate -- <file>
git diff ORIG_HEAD...HEAD -- <file>

5. Run Focused Checks

Run checks that match the files touched by the conflict. Common commands in this repository include:

npm run check:config
python3 scripts/build.py --check
python3 scripts/generate_device_slots.py --check
python3 scripts/check_timezones.py
npm run docs:build

Use the repo-local compile skill when firmware YAML, common YAML, device YAML, or C++ component changes need compile-level confidence.

If a check cannot be run locally, say why and name what remains unverified.

6. Commit and Push

Confirm only intended files changed:

git status --short
git diff --check
git diff --stat

Commit the conflict resolution with a plain message:

git add <resolved-files>
git commit -m "Resolve PR <number> merge conflicts"
git push

If working on a newly created same-repo branch, push with upstream and open a draft PR into the original base branch, explaining that it carries the original PR plus conflict resolutions.

Do not merge the PR, close linked issues, or mark device testing complete unless the user explicitly confirms the tested result.

Output Format

Keep the final update approachable and practical:

Resolved conflicts for PR #<number>: <title>

What changed:
- <plain-English summary of the conflict resolution>

Checks run:
- <command>: <pass/fail/skipped and why>

Pushed:
- <branch or PR URL>

What to test:
- <device/display or workflow the user should test before merge>