Git Conflict Resolution Workflow (git-conflict-resolve)

Overview

A semantics-driven Git conflict resolution protocol that replaces blind -X ours/-X theirs strategies.

For each conflicted file: first run a semantic analysis to understand both sides' intent, then derive a resolution rule (with a confidence level). High-confidence conflicts are resolved automatically; medium-confidence conflicts show a recommendation and wait for confirmation; low-confidence conflicts show a three-way view and wait for a manual decision. After resolution, each file is logically verified one by one, and a final manual-review checklist is generated.

Paired skill: invoked by git-release-finish stage 6; can also be invoked standalone to handle any merge/rebase conflict.

Input Parameters

Standalone invocation example:

Run the git-conflict-resolve skill with source=release/8.2.60, target=master, version=8.2.60, mode=merge

Sub-stage Y.0 — Mode Detection & Initialization

1. Read the input parameters and confirm mode (merge or rebase)
2. Initialize the cumulative conflict file list (a global variable that persists across all rounds — must never be cleared at any point)
3. Initialize according to mode:

merge mode (default):

# Create the merge branch from the target branch (no -X auto strategy, so conflicts surface naturally)
git checkout origin/<TARGET> -b merge-release/<VERSION>
git merge origin/<SOURCE> --no-commit --no-edit

⚠️ Do not use -X ours or -X theirs — blindly picking a side can silently drop logic. Conflicts are decided file-by-file via the semantic analysis below.

rebase mode:

# Create a local working branch from the remote source (avoids polluting the original remote branch)
git checkout origin/<SOURCE> -b rebase-release/<VERSION>

# Replay source's commits one by one onto target
git rebase origin/<TARGET>
# Stops on conflict → proceed to Y.1
# If rebase completes with no conflicts → skip Y.1–Y.4, go straight to Y.5

⚠️ When pushing the rebase result, if the target is a protected branch (release/*, main, master), a force push may be rejected by the remote (remote: rejected). Check branch protection before pushing; if necessary, push to a new branch instead (e.g. rebase-release/<VERSION>) and open a new MR, rather than force-pushing to the original branch.

Sub-stage Y.1 — Conflict Inventory (Cross-round Aggregation)

⚠️ In rebase mode, every time a new conflict appears after git rebase --continue, Y.1 must be re-run, appending the new files to the cumulative list — never replacing it.

# Get the conflicted files for the current round
git diff --name-only --diff-filter=U

Append rule:

cumulative list = cumulative list ∪ current round's conflicted files
(set union — no duplicates, but the round in which each file first appeared is retained)

Output format:

【Conflict inventory — round N】
New conflicted files this round (M):
  - path/to/file-a.ts (new)
  - path/to/file-b.ts (new)

Cumulative conflict file list (K total, across all rounds):
  - path/to/file-a.ts (round 1)
  - path/to/file-b.ts (round 2)
  ...

If the current round's conflict list is empty:

→ If the list is non-empty, proceed to Y.1.5 to check for build artifacts before deciding whether to enter Y.2's semantic analysis.

Sub-stage Y.1.5 — Build-Artifact Short-Circuit (compiled/bundled files)

⚠️ This stage runs before Y.2's semantic analysis — it is the key upfront gate for saving tokens and avoiding mis-resolutions.

Build artifacts (compiled/bundled derived files) are machine-generated: their content is huge (a single minified line can run to hundreds of thousands of characters), so reading them wastes a large number of tokens; compressed code has no "intent from either side" to analyze; and forcing a merge easily leaves conflict markers behind or keeps a stale version. Their authority is always the release branch — the correct approach is to not read, not analyze, and directly take the release side.

For each file in the cumulative list, classify it using the "Build Artifact Identification Checklist" in [reference.md](reference.md) (build-output directory prefixes ∪ file signatures ∪ project-specific additions):

• Matches a build artifact → do not read the three-way content, do not enter Y.2's semantic analysis; resolve directly using the short-circuit table below:

After resolving, still run the Y.4.5 instant verification (scanning for residual conflict markers) to confirm nothing is left behind.

• No match (source code/config) → proceed to Y.2's normal semantic analysis.

⚠️ Default to caution: files with ambiguous boundaries (neither in a known build-output directory nor matching a clear artifact signature) must never be short-circuited — route them through Y.2. Misclassifying source code as a build artifact loses target-side changes, and that cost far outweighs reading one extra file — when in doubt, read it rather than misjudge it.

📖 See [reference.md](reference.md) for the identification checklist, detailed commands for each conflict type, and the rename+hash fallback and rationale.

Sub-stage Y.2 — Semantic Analysis

⚠️ This stage is read-only — do not modify any file.

For each conflicted file, do the following in order:

1. Read the three-way content

git show :1:<FILE>   # BASE: the common ancestor version
git show :2:<FILE>   # main side (ours): the target branch's version
git show :3:<FILE>   # release side (theirs): the source branch's version

Note: in both merge and rebase modes, :2: = the main side and :3: = the release side, with the same semantics.

2. Analyze the change deltas

# Compute the common ancestor
MERGE_BASE=$(git merge-base origin/<SOURCE> origin/<TARGET>)

# What changed on the main side relative to BASE
git diff $MERGE_BASE origin/<TARGET> -- <FILE>

# What changed on the release side relative to BASE
git diff $MERGE_BASE origin/<SOURCE> -- <FILE>

3. Output the semantic description

【Semantic analysis — <FILE>】
main side intent: [unchanged / hotfix / feature development / refactor / deletion / version-field update / other]
  Specific changes: ...

release side intent: [unchanged / hotfix / feature development / refactor / deletion / version-field update / other]
  Specific changes: ...

Relationship between the two sides: [mutually exclusive (one overrides the other) / complementary (both must be kept) / one-sided change (the other side is identical to BASE)]

Sub-stage Y.3 — Rule Derivation

Based on Y.2's semantic-analysis conclusions, derive a resolution rule and confidence level for each file.

The three confidence tiers

Conflict-type identification (prerequisite for derivation)

Before deriving a rule, first identify the conflict's structural type — resolution strategies differ completely by type, and misclassifying one leads to residual conflict markers or lost changes.

Two-step identification:

Step 1 — Determine the broad category from git status:

git status --porcelain                        # conflict status codes
git diff --name-status --diff-filter=U        # rename info

Step 2 — Refine using file signatures:

The primary identification and short-circuiting of build artifacts is already done in Y.1.5 (a match takes the release side and never reaches Y.3). The signature check here is a fallback: if Y.1.5 missed it but Y.3 detects an artifact signature, treat it as a build artifact (take the release side).

# Build-artifact hash file (webpack/vite/rollup chunk)
echo "$FILE" | grep -qE '[0-9a-f]{8,}\.(js|css|map)$'

# Config file
echo "$FILE" | grep -qE '(^|/)(package\.json|tsconfig\.json|\.config\.(js|ts))$'

Rule library

Organized by conflict type + confidence. Match the structural type first, then derive by scenario.

🟢 High-confidence scenarios:

⚠️ Rename + build-artifact hash is an error-prone scenario: a simple git checkout --theirs won't work because the filename changed after the rename — the old hash file must be explicitly deleted and the new file explicitly pulled from release. See Y.4 for the detailed procedure.

🟡 Medium-confidence scenarios:

🔴 Low-confidence scenarios:

Sub-stage Y.4 — Resolution by Category

Process each file in order, according to its Y.3 confidence classification:

🟢 High confidence — resolve automatically

# Take the release side (theirs)
git checkout --theirs <FILE>
git add <FILE>

# Take the main side (ours)
git checkout --ours <FILE>
git add <FILE>

# Take the release side for a whole directory (build artifacts, etc.)
git rm -rfq <DIR>
git checkout origin/<SOURCE> -- <DIR>
git add <DIR>

Rename + build-artifact hash strategy (never reads file content)

This scenario is normally already handled by the Y.1.5 upfront short-circuit (a build-artifact match takes the release side directly). If Y.1.5 didn't catch it (fallback), handle it with this strategy, and prefer git's rename metadata for filenames — never read file content.

After a rename, the filename changes, so git checkout --theirs may point to a path that no longer exists; both the old and new filenames must be handled explicitly:

# 1. Preferred: get both sides' filenames from git's rename metadata (never reads file content)
git diff --name-status --diff-filter=U
# Output looks like: R100 old-abc.js new-def.js → gives OLD_FILE / NEW_FILE

# 1b. Fallback: if rename metadata is missing, extract filenames only from the conflict-marker lines (do not read the full file)
OLD_FILE=$(git show :2:<FILE> | grep "^<<<<<<<" | sed 's/^.*HEAD://')
NEW_FILE=$(git show :3:<FILE> | grep "^>>>>>>>" | sed 's/^.*://' | tail -1)

# 2. Delete the old hash file (otherwise the repo ends up with two functionally identical chunks)
git rm -f "$OLD_FILE" 2>/dev/null

# 3. Take the new hash file from the release branch
git checkout origin/<SOURCE> -- "$NEW_FILE"
git add "$NEW_FILE"

⚠️ Why a plain git checkout --theirs doesn't work: in a rename conflict, the --theirs file path may differ from the current path in the working tree. Failing to delete the old file leaves two functionally identical chunks (old hash + new hash) in the repo, and the build may end up referencing the wrong one.

Output log:

✅ [High confidence] <FILE>
   Rule: release refactored, main unchanged → take the release side
   Action: git checkout --theirs <FILE> && git add <FILE>

🟡 Medium confidence — show a recommendation, wait for user confirmation

【Conflicted file】<FILE>
【main-side change】...
【release-side change】...
【AI recommendation】Favor release; main's hotfix has already been superseded by xxx in release
【Please choose】
A = Accept the AI's recommendation (take the release side)
B = Keep the main side
C = I'll edit it manually — let me know when it's done

🔴 Low confidence — three-way view, wait for the user's decision

【Conflicted file】<FILE>
【BASE (common ancestor), lines X–Y】
...(code)

【main side (ours), lines X–Y】
...(code)

【release side (theirs), lines X–Y】
...(code)

【AI analysis】Both sides made substantive logic changes — cannot determine an authoritative side
【Please choose】
A = Take the release side
B = Take the main side
C = I'll merge it manually — let me know when it's done

Y.4.5 — Instant Verification (mandatory after resolving each file)

⚠️ Fail-fast principle: scan immediately after resolving each file, rather than waiting for Y.5's batch verification. A mistake in a single file is caught right away, and the rollback cost is low (only that one file needs redoing). Waiting until Y.5 risks having already forgotten how that file was resolved.

Immediately after finishing the resolution action for each file in Y.4 (git checkout --theirs/--ours, manual editing, the rename+hash strategy, etc.), run:

# Precise regex matching git's conflict-marker format (7+ chars at line start + space/end-of-line)
# Covers the standard 7-character form, non-standard 8+ character forms, and diff3's ||||||| base marker
git grep -nE '^<{7,} |^={7,}$|^>{7,} |^\|{7,} ' -- "$FILE" 2>/dev/null \
  && {
    echo "❌ $FILE resolution failed: conflict markers remain"
    # Roll back to the conflicted state and re-enter Y.2 for analysis
    git checkout MERGE_HEAD -- "$FILE" 2>/dev/null
    return 1
  } || echo "✅ $FILE is clean"

Why a precise regex instead of a broad match: <<<<<<< (7 < characters + a space) locks onto git's conflict-marker format, excluding things like === separator lines in CSS comments or ASCII art. ^={7,}$ requires a line of pure equals signs to the end of the line, so a CSS comment like / ====== / won't match (there's a */ after the equals signs).

Why git grep instead of grep -r: git grep automatically respects .gitignore and only scans tracked files, naturally excluding untracked build artifacts, which combined with the precise regex forms a double filter.

Continuing a multi-round rebase

Once all files in the current round have been processed:

git rebase --continue

If a new conflict appears → return to Y.1, append to the cumulative list, and continue through Y.2–Y.4. If the rebase completes → proceed to Y.5.

Sub-stage Y.5 — Logic Verification

Verify every file in the cumulative list one by one (not just the current round).

1. Verify release intent is fully preserved

# Compare the resolution result against the original release-side version
git show origin/<SOURCE> -- <FILE>

Check: are the release side's key changes (functions, imports, logic blocks) fully preserved in the resolution result?

2. Verify main's necessary changes

# Compare the resolution result against the original main-side version
git show origin/<TARGET> -- <FILE>

Check: were any independent, necessary changes on the main side (e.g. a hotfix) mistakenly dropped?

3. Check for residual conflict markers (within the cumulative list)

Do not scan the whole repo. Only scan the files in Y.1's cumulative list — these are the only files involved in this conflict resolution, and thus the only place markers could remain. A whole-repo scan would be swamped by false positives from things like CSS comments in build artifacts.

# Scan only the cumulative-list files, using a precise regex for git's conflict-marker format
for FILE in $CONFLICT_FILES_CUMULATIVE; do
  git grep -nE '^<{7,} |^={7,}$|^>{7,} |^\|{7,} ' -- "$FILE" 2>/dev/null \
    && echo "❌ $FILE has residual markers"
done

⚠️ Warning criteria (mark as ⚠️ if any apply):

• A function/class/method that exists on the release side has disappeared from the resolution result
• Code that release deleted has reappeared in the resolution result (i.e. it was "reverted")
• An import statement from the release side is missing from the resolution result
• A version field (version/testVersion) doesn't match the release side
• release refactored some logic, but the resolution result fell back to the old implementation

❌ Failure criteria (mark as ❌ if any apply):

• The file still contains residual conflict markers (<<<<<<<, =======, >>>>>>>)
• The same function/variable appears twice in the resolution result (a duplicated merge)
• There's an obvious syntax error (e.g. an extra }, an unclosed bracket)

Verification output:

✅ <FILE> — logically consistent (release intent fully preserved, main's necessary changes handled)
⚠️ <FILE> — possibly lost a release change: function/logic xxx does not appear in the resolution result
❌ <FILE> — logic conflict: residual <<<<< markers or an obvious semantic contradiction

⚠️/❌ files: must not be committed — they must be reprocessed before proceeding to Y.6.

Sub-stage Y.6 — Global Review Checklist + Commit

Output a summary table (covering all files in the cumulative list):

⚠️ The following files were changed during this conflict resolution — please review them carefully:

| File | Round appeared | Resolution | Confidence | Logic verification | Needs extra review |
|------|---------|---------|--------|---------|----------|
| src/effects/database/search-database.ts | round 1 | AI automatic (took release side) | 🟢 High | ✅ | — |
| package.json | round 1 | AI automatic (took release's version field) | 🟢 High | ✅ | — |
| src/components/editor.tsx | round 2 | User chose A (release side) | 🟡 Medium | ✅ | — |
| src/utils/helper.ts | round 1 | User merged manually | 🔴 Low | ⚠️ | ⚠️ Needs review |

Files that need extra review (⚠️/❌ verification, or 🔴 low confidence):
  - src/utils/helper.ts: verification result ⚠️, possibly lost a release change

After confirming the files above are logically correct, reply "continue" to complete the commit.

After user confirmation (execute per mode):

merge mode:

git add -A

⚠️ Pre-commit gate (L2 defense): before git commit, scan all staged files for residual conflict markers. This is the last line of defense before committing — it can still catch problems even if the Y.4.5 instant verification was skipped or went wrong.

# Scan all staged files
git diff --cached --name-only | while read f; do
  git grep -lE '^<{7,} |^={7,}$|^>{7,} |^\|{7,} ' -- "$f" 2>/dev/null \
    && { echo "❌ Commit blocked: $f still contains conflict markers"; exit 1; }
done
# exit 1 → blocks the commit, go back to Y.4 to reprocess that file

Once the gate passes:

git commit --no-verify -m "Merge release/<VERSION> into <TARGET>"

⚠️ Only use --no-verify when pre-commit hooks block the merge commit for reasons like formatting warnings; if the hooks run type checks, fix the errors instead.

rebase mode:

# Each rebased commit has already been applied individually — no extra merge commit is needed
# Notify the caller (git-release-finish) to perform the final force-push
git rebase --continue   # if commits remain to finish from the last round
# Once the rebase completes, exit and let git-release-finish stage 6 take over the force-push

Prohibited Behaviors (Red Flags)

The following behaviors violate this protocol. If the AI notices it is about to do one of these, it must stop immediately and return to the correct step.

Error Handling

Quick Reference Commands

# ── Conflict-marker detection (precise regex, shared by every defense layer) ──
# Matches git's conflict-marker format: 7+ characters at line start + space/end-of-line
# Covers the standard 7-character form, non-standard 8+ character forms, and diff3's ||||||| base marker
RE='^<{7,} |^={7,}$|^>{7,} |^\|{7,} '

# Y.4.5 single-file instant verification
git grep -nE "$RE" -- "$FILE" 2>/dev/null

# Y.5 cumulative-list scan
for f in $CONFLICT_FILES; do git grep -lE "$RE" -- "$f" 2>/dev/null; done

# Y.6 pre-commit gate (staged files)
git diff --cached --name-only | while read f; do
  git grep -lE "$RE" -- "$f" 2>/dev/null && echo "❌ $f"
done

# ── Three-way version content ──
git show :1:<file>   # BASE
git show :2:<file>   # main side (ours)
git show :3:<file>   # release side (theirs)

# Each side's delta (compute MERGE_BASE first)
MERGE_BASE=$(git merge-base origin/$SRC origin/$TGT)
git diff $MERGE_BASE origin/$TGT -- <file>   # main's delta
git diff $MERGE_BASE origin/$SRC -- <file>   # release's delta

# ── Conflict-type identification ──
git status --porcelain                        # conflict status codes (UU/AA/DU/UD)
git diff --name-status --diff-filter=U        # rename info

# ── Resolve by confidence ──
git checkout --theirs <file> && git add <file>   # take the release side
git checkout --ours <file> && git add <file>     # take the main side

# Y.1.5 build-artifact short-circuit (match → take release side, no content read)
git checkout --theirs <file> && git add <file>                                       # content conflict / Add-Add
git rm -rfq <dir> && git checkout origin/<SOURCE> -- <dir> && git add <dir>           # whole-directory artifact

# rename + build-artifact hash (prefer rename metadata, never read file content)
git diff --name-status --diff-filter=U                                               # get OLD/NEW filenames
git rm -f "$OLD" 2>/dev/null && git checkout origin/<SOURCE> -- "$NEW" && git add "$NEW"

# continue the rebase
git rebase --continue