cs-conflict
Resolve merge conflicts for a PR or current branch — auto-resolves obvious conflicts, interactive resolution for ambiguous ones
SKILL.mdskills/conflict/SKILL.md
GitHubPR Merge Conflict Resolver
You are a senior engineer resolving merge conflicts. Given a PR number or current branch, you detect conflicts, auto-resolve obvious ones (imports, formatting, non-overlapping additions), and interactively resolve ambiguous ones.
Inputs
$ARGUMENTS — PR number (optional). If empty, uses current branch.
Step 1: Gather Context
1.1: Determine branches
If PR number given:
gh pr view $ARGUMENTS --json headRefName,baseRefName,title,number
If command fails (non-zero exit code, or PR not found), output:
Error: Could not fetch PR #$ARGUMENTS. Verify the PR number and that `gh` is authenticated.
Stop here.
Parse JSON → HEAD_BRANCH = headRefName, BASE_BRANCH = baseRefName, PR_TITLE = title, PR_NUMBER = number.
Checkout the PR branch:
git checkout <HEAD_BRANCH>
If checkout fails (branch not found locally or remotely), try:
gh pr checkout $ARGUMENTS
If still fails, output error and stop.
git pull origin <HEAD_BRANCH>
If no PR number:
git branch --show-current
Set HEAD_BRANCH to current branch. If HEAD is detached, output:
Error: Detached HEAD state. Please checkout a branch first.
Stop here.
Detect base branch by looking up the open PR for this branch first:
gh pr list --head <HEAD_BRANCH> --state open --json number,baseRefName,title --limit 1
If the result is a non-empty JSON array:
- Parse →
BASE_BRANCH= baseRefName,PR_NUMBER= number,PR_TITLE= title
If the result is empty (no open PR found), fall back to remote default branch:
git remote show origin | grep "HEAD branch"
If that also fails (no remote, no network), fall back:
git branch -l main master develop
Use the first branch that exists. If none exist, output:
Error: Could not detect base branch. Specify a PR number instead: /cs-conflict <PR#>
Stop here.
Set BASE_BRANCH to the result. If PR was not found via gh pr list, set PR_NUMBER to empty, PR_TITLE to empty.
1.2: Check working tree & save restore point
git status --porcelain
If output is non-empty (uncommitted changes exist):
git stash push -m "cs-conflict: auto-stash before merge"
Save STASHED = true. If stash fails, output:
Cannot proceed: uncommitted changes detected and stash failed.
Please commit or stash your changes manually, then re-run /cs-conflict.
Stop here.
If working tree is clean, set STASHED = false.
Then save restore point:
git rev-parse HEAD
Save the output as RESTORE_SHA. This is the fallback for abort.
1.3: Fetch and attempt merge
git fetch origin <BASE_BRANCH>
git merge origin/<BASE_BRANCH> --no-commit --no-ff
If merge succeeds (exit code 0): no conflicts exist.
git merge --abort
If STASHED = true:
git stash pop
Output:
## Conflict Resolution: <HEAD_BRANCH> <- <BASE_BRANCH>
No merge conflicts detected. The branch can be merged cleanly.
Stop here. Do not proceed to Step 2.
If merge fails (exit code 1): conflicts exist. Continue to Step 2.
Step 2: Identify Conflicted Files
git diff --name-only --diff-filter=U
Save as CONFLICT_FILES. Output the numbered list:
Found N conflicted files:
1. src/services/user.service.ts
2. src/utils/helpers.ts
3. package-lock.json
Step 3: Analyze & Categorize Conflicts
Read each file in CONFLICT_FILES using the Read tool. For each file, find all conflict regions (delimited by <<<<<<<, =======, >>>>>>>).
Categorize each conflict region into one of these types:
AUTO-resolvable categories
| Category | Detection | Strategy |
|---|---|---|
| Import ordering | Both sides add/reorder import statements, no semantic overlap | Merge + deduplicate + sort alphabetically |
| Formatting-only | Diff is whitespace, semicolons, trailing commas, quote style only | Accept HEAD (ours) |
| Non-overlapping additions | Both sides add new code at the same location but the additions are independent (different functions, different properties, different lines) | Keep both — ours first, then theirs |
| Deleted vs unchanged | One side deletes code, other side keeps it unchanged (no modifications) | Accept deletion |
| Lock files | File is package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, Gemfile.lock, poetry.lock, composer.lock |
Accept theirs to clear conflict state, then flag for regeneration |
MANUAL-resolution categories
| Category | Detection |
|---|---|
| Overlapping logic | Both sides modify the same lines of functional code |
| Structural conflict | Changes to function signatures, class structure, type definitions that affect both sides |
| Same insertion point | Both sides add different functional code at the exact same location |
Build a summary for each file:
File: src/services/user.service.ts
Region 1 (lines 5-12): AUTO — Import ordering (merge + deduplicate)
Region 2 (lines 45-60): MANUAL — Overlapping logic (both sides modify validateUser)
File: package-lock.json
AUTO — Lock file (flag for regeneration)
Step 4: Present Analysis & Confirm
Output the full categorized summary as plain text:
## Conflict Analysis
**Auto-resolvable:** N conflicts across M files
**Manual resolution needed:** X conflicts across Y files
**Lock files:** K files (will be flagged for regeneration)
### Auto-Resolvable
1. src/utils/helpers.ts:5-12 — Import ordering (merge + deduplicate)
2. src/utils/helpers.ts:30-35 — Non-overlapping additions (keep both)
3. src/components/Button.tsx:1-8 — Formatting-only (accept ours)
### Manual Resolution Needed
4. src/services/user.service.ts:45-60 — Overlapping logic
5. src/services/user.service.ts:80-95 — Structural conflict
### Lock Files
6. package-lock.json — Regenerate after resolution
Then use AskUserQuestion:
- question: "How should conflicts be resolved?"
- options (exactly 3):
| Option | Description |
|---|---|
| Proceed (Recommended) | Auto-resolve obvious conflicts, then handle manual ones interactively |
| Review each | Review every conflict interactively, including auto-resolvable ones |
| Abort | Cancel merge and restore branch to original state |
If Abort → jump to Abort Procedure.
If Review each → treat all conflicts as MANUAL in Steps 5 and 6.
Step 5: Auto-Resolve
Process files one at a time (skip if user chose "Review each"). For each file with AUTO conflicts:
- Resolve ALL conflict regions in the file — apply the resolution strategy using the Edit tool for each region, removing conflict markers (
<<<<<<<,=======,>>>>>>>) and applying the merged content - Only after ALL regions in the file are resolved, stage it:
git add <FILE_PATH>
Important: If a file has mixed regions (some AUTO + some MANUAL), do NOT stage it in Step 5. Leave it for Step 6 — resolve the remaining MANUAL regions first, then stage.
For lock files: do NOT edit textually. Clear the conflict state so they don't block the commit:
git checkout --theirs <LOCK_FILE>
git add <LOCK_FILE>
Note them for the regeneration reminder in Step 7 (regeneration will overwrite this placeholder).
After all auto-resolutions, output:
### Auto-Resolved
| # | File | Strategy |
|---|---|---|
| 1 | src/utils/helpers.ts:5-12 | Import ordering — merged + deduplicated |
| 2 | src/utils/helpers.ts:30-35 | Non-overlapping additions — kept both |
| 3 | src/components/Button.tsx:1-8 | Formatting-only — accepted ours |
If no MANUAL conflicts remain, skip to Step 7.
Step 6: Manual Resolution
For each MANUAL conflict (or all conflicts if "Review each" was chosen):
6.1: Show conflict context
Display the conflict with both sides clearly labeled:
### File: src/services/user.service.ts (lines 45-60)
**Type:** Overlapping logic
**Ours (HEAD — <HEAD_BRANCH>):**
[code from ours side]
**Theirs (origin/<BASE_BRANCH>):**
[code from theirs side]
**Context:** [1-line explanation — e.g., "Both sides modify the validateUser function: ours adds email validation, theirs adds phone validation"]
6.2: Ask for resolution
Use AskUserQuestion:
- question: "How to resolve this conflict? (<FILE>:<LINES>)"
- options (exactly 4):
| Option | Description |
|---|---|
| Ours | Keep HEAD version (current branch) |
| Theirs | Keep base branch version |
| Merge both | Combine both changes into one |
| Skip | Leave unresolved for now |
If Ours: Edit the file to keep only the ours side, remove conflict markers.
If Theirs: Edit the file to keep only the theirs side, remove conflict markers.
If Merge both: Propose a merged version that combines both changes. Show the proposed code, then use AskUserQuestion:
- question: "Accept this merged code?"
- options (exactly 2):
| Option | Description |
|---|---|
| Accept (Recommended) | Use the proposed merged code |
| Edit | Describe what to change |
If Edit, apply the user's requested changes, show the updated code, and re-confirm with the same Accept/Edit question. Then Edit the file with the final version.
If Skip: Leave the conflict markers in place. Note as skipped.
6.3: Stage resolved files
After processing all regions for a file, check if ALL conflict regions in that file are resolved (none were Skipped). If yes:
git add <FILE_PATH>
If any region in the file was Skipped, do NOT stage the file — it still contains conflict markers.
After all manual resolutions, output:
### Manually Resolved
| # | File | Resolution |
|---|---|---|
| 4 | src/services/user.service.ts:45-60 | Merge both — combined email + phone validation |
| 5 | src/services/user.service.ts:80-95 | Theirs — accepted base branch type definition |
Step 7: Finalize
7.1: Check remaining conflicts
git diff --name-only --diff-filter=U
If any files remain unresolved (were Skipped), git will NOT allow a merge commit. Handle this:
If ALL conflicts were skipped (nothing staged):
No conflicts were resolved. Aborting merge.
Run the Abort Procedure. Stop here.
If some conflicts were skipped (partial resolution):
**Warning:** N files still have unresolved conflicts:
- <file list>
Git requires ALL conflicts to be resolved for a merge commit.
Use AskUserQuestion:
- question: "How to handle unresolved files?"
- options (exactly 3):
| Option | Description |
|---|---|
| Accept ours (Recommended) | Keep HEAD version for all unresolved files, complete the merge |
| Accept theirs | Keep base branch version for all unresolved files, complete the merge |
| Abort | Cancel merge and restore branch to original state |
If Abort → run Abort Procedure.
If Accept ours or Accept theirs: for each unresolved file:
git checkout --ours <FILE_PATH>
or:
git checkout --theirs <FILE_PATH>
git add <FILE_PATH>
7.2: Lint check
Read package.json and extract all lint-related scripts (keys containing lint or biome, case-insensitive).
If no lint scripts found: skip this step entirely.
If lint scripts found:
Detect the package manager from lock file presence:
bun.lockb→bun runpnpm-lock.yaml→pnpm runyarn.lock→yarnpackage-lock.jsonor fallback →npm run
Run each detected lint script in order:
<PM> run lint
<PM> run biome:lint
(Skip scripts that are clearly fix-only, e.g. lint:fix, biome:fix — run those only during auto-fix.)
If all lint scripts pass: continue to 7.3.
If any lint script fails: show the full error output, then use AskUserQuestion:
- question: "Lint errors found after conflict resolution. How to proceed?"
- options (exactly 3):
| Option | Description |
|---|---|
| Auto-fix (Recommended) | Run fix scripts (lint:fix, biome:fix, or --fix variant) and re-stage |
| Commit anyway | Ignore lint errors and commit as-is |
| Abort | Cancel merge and restore branch |
If Auto-fix:
Run available fix scripts detected from package.json (prefer explicit fix scripts over adding --fix flag):
<PM> run lint:fix # if exists
<PM> run biome:fix # if exists
<PM> run biome:check --fix # fallback if biome:fix not present
Re-stage resolved files after auto-fix:
git add <RESOLVED_FILES>
If lint still fails after auto-fix, show remaining errors and continue to commit (some errors may not be auto-fixable).
If Abort → run Abort Procedure.
7.3: Show staged changes summary
git diff --cached --stat
Output the result.
7.4: Suggest commit message
Do NOT run git commit. Output the suggested commit command for the user to run manually:
### Ready to commit
All conflicts resolved and staged. Run this to commit:
```bash
git commit -m "Resolve merge conflicts: <HEAD_BRANCH> <- origin/<BASE_BRANCH>"
**Important:** Do NOT add `Co-Authored-By`, `Signed-off-by`, or any AI/Claude attribution to commits.
### 7.5: Restore stash
If `STASHED = true`:
```bash
git stash pop
If stash pop fails (conflicts with merged result), output:
Warning: Could not restore stashed changes automatically. Run `git stash pop` manually and resolve.
7.6: Lock file reminder
If any lock files were in the conflict list, output a reminder to regenerate each one with the appropriate install command for its package manager, then commit separately.
Step 8: Output
## Conflict Resolution: <HEAD_BRANCH> <- <BASE_BRANCH>
**PR:** #<PR_NUMBER> — <PR_TITLE>
### Auto-Resolved (N)
| # | File | Strategy |
|---|---|---|
| ... | ... | ... |
### Manually Resolved (M)
| # | File | Resolution |
|---|---|---|
| ... | ... | ... |
### Skipped (K)
| # | File | Reason |
|---|---|---|
| ... | ... | ... |
### Lock Files (regenerate with install command)
- [lock file list]
### Next step
```bash
git commit -m "Resolve merge conflicts: <HEAD_BRANCH> <- origin/<BASE_BRANCH>"
If no PR number was given, omit the `**PR:**` line.
## Abort Procedure
When abort is triggered (user chooses Abort, or an error occurs):
1. Try clean abort:
```bash
git merge --abort
- If
git merge --abortfails, fall back to hard reset:
git reset --hard <RESTORE_SHA>
- Verify restoration:
git rev-parse HEAD
Confirm the SHA matches RESTORE_SHA.
- If
STASHED = true, restore the stash:
git stash pop
Output:
Merge aborted. Branch restored to original state (<RESTORE_SHA>).
If stash was restored, add: Stashed changes have been restored.
Important
- Interactive only — conflict resolution is inherently risky, no auto-only variant exists
- Never force-push — if push fails, report the error and stop
- No AI attribution — no
Co-Authored-ByorSigned-off-byin commits