---
name: resolving-merge-conflicts
description: Use when a git merge or rebase is already in progress and conflicted, and hunks need resolving before it can finish.
---

# Resolving Merge Conflicts

Resolve by **intent**, traced to each side's primary source, rather than by picking lines that look
right. **Always finish the operation. Never `--abort`.**

1. **See the current state.** Which operation is in flight (`git status`), which files conflict, and
   what the two sides are (`git log --oneline HEAD..MERGE_HEAD`, or the rebase's `onto`).

2. **Find the primary source for each side.** Understand *why* each change was made and what it was
   for: read the commit messages, the merge request, and the ticket behind it. For KACP work the Jira
   story is the primary source, and `.claude/docs/epics/` may already hold it. A hunk resolved without
   knowing what either side was trying to do is a guess wearing a resolution's clothes.

3. **Resolve each hunk.** Preserve both intents wherever they can coexist. Where they genuinely
   conflict, take the one matching the stated goal of *this* merge and say so, noting the trade-off.
   **Invent no new behaviour**: a conflict resolution is not the place for a third design neither
   side asked for.

4. **Run the project's checks.** Discover them rather than assuming: `package.json` scripts are the
   source of truth. Typecheck, then tests, then format. Fix whatever the merge broke.

5. **Finish the operation.** Stage everything and commit. On a rebase, continue until every commit is
   replayed.

## Done when

- Every hunk was resolved against a primary source, not by appearance.
- No behaviour exists that neither side had.
- The project's typecheck and tests pass.
- The merge or rebase is completed, never aborted.