Hk Merge Resolve

Resolve Merge Conflicts

Your job is to resolve all merge conflicts in the current branch of the current repo.

Conflicts can come from many sources — git merge, git rebase, git stash pop, git cherry-pick, or any operation that combines divergent changes. This skill handles all of them.

Step 0: Diagnose the Situation

Before changing anything, understand what state git is in and what caused the conflicts.

1. Snapshot the state — Run these to understand what's happening:

   git status
   git rev-parse HEAD

   Print the HEAD sha to the user: "Safety checkpoint: HEAD is at <sha>."

2. Identify the conflict source — Check which operation is in progress:

   • git rev-parse MERGE_HEAD 2>/dev/null → merge in progress
   • test -d .git/rebase-merge || test -d .git/rebase-apply → rebase in progress
   • git stash list + check git status for "Unmerged paths" without MERGE_HEAD → stash pop conflict

   This matters because the abort/recovery command differs:

   Source	Abort command
   merge	git merge --abort
   rebase	git rebase --abort
   cherry-pick	git cherry-pick --abort
   stash pop	git checkout -- . (stash stays in list, nothing lost)

   Print the appropriate abort command to the user so they have an escape hatch.

3. Protect unstashed work — If there are uncommitted changes beyond the conflicted files (tracked modified files that aren't part of the conflict), warn the user. These are at risk during resolution. Suggest committing or stashing them separately before proceeding, and wait for confirmation.

   Do NOT blindly git stash when conflicts are already present — git won't allow it, and if the conflicts came from a stash pop, the user's changes are already in the working tree as the conflicted content. Stashing again would lose them.

Step 1: Build Context

Understand what both sides of the conflict were trying to do:

1. Identify the two sides — Based on the conflict source:

   • Merge: "ours" = current branch, "theirs" = the branch being merged in
   • Stash pop: "ours" = current working tree (post-pull), "theirs" = the stashed changes (the user's local work)
   • Rebase: "ours" = the branch being rebased onto, "theirs" = the commits being replayed

   Understanding which side is which is critical — especially for stash pop conflicts where "theirs" is the user's own work and should generally be preserved.

2. Find all conflicts — Use Grep to search for <<<<<<< across the repo. This gives you the full list of files and locations.

3. Triage — Group conflicts before diving in:

   • Trivial: Lock files, auto-generated files, whitespace-only — resolve mechanically.
   • Straightforward: Both sides changed different things in the same region — combine them.
   • Requires judgment: Both sides changed the same logic — need to understand intent.

Step 2: Resolve Each Conflict

For each conflicted file, read the file (or at minimum the conflicted region with surrounding context), then decide:

1. Keep ours — when the incoming changes are superseded
2. Keep theirs — when the incoming side has the better version
3. Combine both — the most common case; merge both sides' intent into correct code

For stash pop conflicts: The user's stashed changes are their in-progress work. Default to preserving the user's intent — their local changes are the "important" side. The pulled/merged content is the "environment" that the user's work needs to be adapted to.

Correctness matters more than cleverness. When combining:

• Understand what each side was trying to do
• Write the result that achieves both goals
• Make sure imports, variable names, and types are consistent across the merged result

For each conflict:

1. Read the file to see the full conflict region with context
2. Edit the file to the desired final state — remove ALL conflict markers (<<<<<<<, =======, >>>>>>>)
3. Stage the resolved file with git add <file>

After resolving all conflicts in a file, do a quick sanity check: does the file still make sense? Are imports consistent? Are there dangling references?

Step 3: Verify — Close the Loop

After all conflicts are resolved, verification is mandatory, not optional. A merge that compiles is not a merge that works.

3a. Confirm clean state

git diff --check          # No conflict markers remain
grep -rn '<<<<<<<' .      # Belt-and-suspenders: grep for stray markers

If either finds markers, go back and fix them before proceeding.