hk-merge-resolve

name	hk-merge-resolve
description	Resolve merge conflicts in the current branch. Only invoke when the user explicitly runs /hk-merge-resolve. Do NOT auto-trigger on mentions of merge conflicts, conflict markers, or similar keywords.
allowed-tools	Bash, Read, Edit, Grep, Glob, AskUserQuestion

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.

3b. Determine affected projects

Check which parts of the monorepo were touched by the merge. Run:

# For merge: diff between merge base and current state
git diff --name-only $(git merge-base HEAD MERGE_HEAD) HEAD 2>/dev/null || \
  git diff --name-only HEAD~1 HEAD  # fallback for rebase/cherry-pick

Map changed files to projects:

Path prefix	Project	Check commands
taskit/taskit-frontend/	Frontend	npm run build (TypeScript + Vite), npm run lint
taskit/taskit-backend/	Backend	`cd taskit/taskit-backend && python manage.py check --deploy 2>/dev/null
odin/	Odin	cd odin && python -m pytest tests/unit/ -v
harness_usage_status/	Harness Usage	cd harness_usage_status && python -m pytest tests/ -v 2>/dev/null

3c. Run check commands for affected projects

Run only the checks for projects that had conflicted files or files changed by the merge. Do not run checks for unaffected projects — that wastes time and may surface pre-existing issues unrelated to the merge.

Execution order:

1. Type checks / build first — catches structural problems (missing imports, type errors, broken references). These are the most likely merge casualties.
2. Lint second — catches style issues introduced by conflict resolution.
3. Fast tests last — unit tests for the affected project. Skip integration/e2e tests (too slow for merge verification; those belong in CI).

For each check:

• Run the command
• If it passes: note it and move on
• If it fails: analyze the failure. If it's clearly caused by the merge resolution (missing import, type mismatch, duplicated declaration), fix it immediately and re-run. If it's a pre-existing failure unrelated to the merge, note it for the user but don't block on it.

Frontend-specific (most common merge casualty in this repo):

cd taskit/taskit-frontend && npm run build

This runs TypeScript type-checking AND Vite bundling — it catches duplicate imports, missing exports, type mismatches, and broken references. This single command is the highest-value check for frontend merges.

Backend-specific:

cd taskit/taskit-backend && python manage.py check

Catches model inconsistencies, migration conflicts, and configuration problems.

Odin-specific:

cd odin && python -m pytest tests/unit/ -v --tb=short

Fast unit tests only. Mock and integration tests are too slow for merge verification.

3d. Report results

After all checks complete, print a summary:

Merge verification:
  ✓ No conflict markers remaining
  ✓ Frontend build passed (TypeScript + Vite)
  ✓ Frontend lint passed
  ✗ Backend check failed — missing migration (see output above)
  — Odin tests skipped (no odin/ files in merge)

If any check failed due to the merge, fix it before completing the merge operation (git merge --continue, git rebase --continue, etc.). Do NOT finalize a merge with known check failures — that defeats the purpose of conflict resolution.

3e. Complete the merge operation

Only after all checks pass (or pre-existing failures are identified and noted):

• Merge: git commit (git usually has the merge commit staged already)
• Rebase: git rebase --continue
• Cherry-pick: git cherry-pick --continue
• Stash pop: No git command needed — files are already in working tree

Ask the user before running the finalization command.

When You're Not Sure

If a conflict involves complex logic where both sides made substantial changes to the same code, and you're not confident about the correct resolution — stop and ask.

Show the user:

1. The conflicting chunks (both sides)
2. Your understanding of what each side intended
3. Your proposed resolution (or the options you see)

Then wait for confirmation before editing. A wrong merge is worse than a slow merge.