/melt

When to invoke: Resolve git merge, rebase, or cherry-pick conflicts via a structural-merge cascade — mergiraf (AST-aware auto-resolve) → git rerere (replay remembered fixes) → kdiff3 (manual fallback). Use when conflicts exist and the user wants them resolved — phrases like “melt the conflicts”, “fix the merge conflicts”, “resolve the rebase conflicts”, “what’s conflicting after the merge”, “/melt”, “fix the cherry-pick”, or any prompt that surfaces <<<<<<< markers, CONFLICT (...) git output, or a half-finished merge state. Use even when only one file is conflicting if the user wants the structural pass attempted before manual editing. Do NOT use for general git operations without conflicts. After /cook or /cure if a merge step blocked them; before retrying the gate that surfaced the conflict.

Use this skill to resolve git merge, rebase, or cherry-pick conflicts using the structural cascade: mergiraf → rerere → kdiff3. Each tool handles what the previous could not.

File IO routing

For conflict-marker or symbol search, bounded inspection, and manual edits, call the selected source-code backend directly according to code-intelligence-routing.md. Preserve search → fresh bounded read → stale-safe write when applying a manual resolution.

Cascade

Stage	Tool	What it does	When it runs
1	`mergiraf`	Tree-sitter structural merge of base / ours / theirs. Independent additions merge cleanly even when text merge would conflict. Falls back to text merge on parse failure.	Automatically as a git merge driver, or via `python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve`.
2	`git rerere`	Replays a previously recorded human resolution for the same conflict signature.	After mergiraf, especially during long rebases where conflicts recur.
3	`kdiff3`	Manual 3-way diff for what mergiraf and rerere could not resolve.	Launched via `git mergetool`.

Protocol

0. Squash-residue check

Run this before the conflict summary. If the branch was squash-merged into base, mergiraf cannot help — see the two remedies below.

python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz detect-squash-residue

If the verdict is SQUASH-MERGED, surface both printed remedies to the user verbatim and stop the cascade. Neither remedy is auto-applied — the user picks one and copy-pastes. Flags:

--base — base ref to compare against (default: origin/main).
--branch — branch to check (default: current).
--json — structured output for scripting.

Detection cascade (strongest first; later signals run only when needed):

tree-match — walks commits on base looking for one whose tree equals the tree at some point on the branch. That commit is a squash-equivalent of branch commits up to that point. Works offline, through fork PRs and renames, and handles branches with commits past the squash (the case local-synth misses). Always runs first.
gh-api — runs in parallel with tree-match. Enriches a tree-match verdict with PR metadata (number, URL, merge commit) when its SHAs correlate with the squash; supplies the verdict on its own when tree-match found nothing.
local-synth — synthesizes a would-be squash commit from HEAD’s tree and asks git cherry whether base contains an equivalent. Last-resort fallback that only runs when neither tree-match nor gh-api produced a verdict; cannot enumerate squashed vs unique commits.

Verdict semantics:

SQUASH-MERGED (method=tree-match or tree-match+gh) — strongest signal; unique-commit list is the slice of branch commits after the matched squash point.
SQUASH-MERGED (method=gh-api) — fallback when tree-match found nothing but the gh PR’s SHAs overlap with branch commits.
SQUASH-MERGED (method=local-synth) — detected offline only; cherry-pick list must be reviewed by hand.
not-detected — proceed to the cascade.
not-applicable — on the base branch.

The detector prints two remedies in order:

[A] merge (non-destructive) — git merge <base>. Preserves all branch history; squashed commits collapse to a no-op merge, so only real conflicts surface. Prefer this when the branch has unique work or the unique-commit list is uncertain.
[B] reset-and-cherry-pick (destructive) — git reset --hard <base> + git cherry-pick <unique-shas>. Rewrites the branch and requires force-push. Use when a clean linear history is wanted and the unique-commit list looks complete.

Default to suggesting [A] first; only suggest [B] when the user has stated a preference for a linear-history workflow or the unique-commit count is small and verified.

1. Diagnose

Run the summary script next.

python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-summary

Default output is terse: one metadata line per file plus minimally framed hunks. Flags:

--json — structured output for scripting.
--verbose — markdown view for humans.
--context N — context lines around each hunk (default 3).

For raw git context:

git log --merge --oneline    # commits involved in the merge
git status                    # conflict / staging state

2. Structural resolution

For every file mergiraf supports, attempt structural merge:

# Preview (dry-run is the default)
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve

# Apply clean resolutions and stage them
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve --apply

# Markdown output and mergiraf debug logs
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve --verbose

To inspect what mergiraf would produce for a single file without touching the working copy, use --debug:

python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve --debug <path>

It prints paths to the merged output, the log, and the conflict-marker count. Inspect with cat/diff against the printed paths; if the merged output is clean, apply it:

cp <merged_path> <path>
git add <path>

3. Remaining conflicts

After the structural pass, check rerere first:

git rerere status      # files with recorded resolutions
git rerere diff        # show what rerere would apply

If rerere already applied, the conflict is resolved. Otherwise drop into the manual tool:

git mergetool          # opens kdiff3 for each conflicted file
git mergetool <path>   # or just one file

After manual resolution, finish the interrupted operation:

git add <resolved-files>
git merge --continue        # or
git rebase --continue       # or
git cherry-pick --continue

Done = git status shows no Unmerged paths AND zero <<<<<<< markers remain.

For ours/theirs picks, lockfiles, mergiraf debugging, and maintenance, see references/cascade-stages.md.

Scripts

Script	Purpose	When
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz detect-squash-residue`	Detect that the branch was squash-merged and emit both the merge and reset+cherry-pick remedies	Run first — short-circuits the cascade
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-summary`	Structured summary with line numbers and context	After residue check
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve`	Run `mergiraf merge` over every conflicted file	Supported languages
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-pick`	Choose ours / theirs per hunk	Shell, SQL, formats mergiraf does not parse
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz lockfile-resolve`	Take one side and regenerate the lockfile	`Cargo.lock`, `package-lock.json`, etc.

What this skill does NOT do

Push or open PRs — hand off to a gh skill.
Run builds or tests — re-enter /cook or run project gates.
Commit resolved files outside git add staging — use a commit skill.
Architectural review of merge results — use /age.

Gotchas

mergiraf solve flag confusion: use --stdout / -p for preview, NOT --output.
Markdown is supported by mergiraf but may need .gitattributes registration.
Lockfile structural merge is not the same as a valid lockfile — always regenerate after taking a side.
zdiff3 base markers (|||||||) are handled by every script in this skill.
If you see conflicts in a supported file type, mergiraf-as-driver already ran — you are looking at the residue.

Handoff

After resolution finishes, prompt the next step via the shared handoff gate in ../cheese/references/handoff-gate.md. Include the detected interrupted operation and upstream invocation in the context packet before asking. Default options:

Resume — dispatch the exact continuation command for the current operation (git merge --continue, git rebase --continue, or git cherry-pick --continue). If the triggering skill invocation is known, return to that skill with the original context after the git operation succeeds; otherwise stop with the resumed git status.
Re-run gates — dispatch the upstream skill invocation that originally surfaced the conflict so its quality gates run on the merged state.
Stop — dispatch none; leave the working tree staged for the user to inspect.

/melt never resumes before the user selects. After a non-stop selection, run the selected continuation immediately.

Cascade stages — branch-specific steps

Steps 0-3 (squash-residue check, diagnose, structural resolution, rerere/manual) run on every invocation and live in the main SKILL.md. Steps 4-7 and special cases below apply only when specific conflict types arise.

Step 4 — Pick ours / theirs (mergiraf-unsupported files)

For shell, SQL, YAML, JSON, and other formats mergiraf does not parse, use conflict-pick:

# Take ours for every hunk
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-pick hooks/session-start.sh --ours

# Take theirs for every hunk
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-pick .gitignore --theirs

# Match by regex; matched hunks resolve, others remain
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-pick config.yaml --grep "timeout" --ours

Step 5 — Lockfiles

Lockfile content has structure that text or AST merge cannot validate. Take one side and regenerate from the manifest:

# Auto-detect conflicted lockfiles, take theirs, regenerate, stage
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz lockfile-resolve

# Preview
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz lockfile-resolve --dry-run

# Take ours instead
python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz lockfile-resolve --strategy ours

Supports Cargo.lock, package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, Pipfile.lock, uv.lock, Gemfile.lock, and go.sum.

Step 6 — Debug mergiraf

When mergiraf is not resolving something it should, start with the --debug single-file inspection in step 2 of SKILL.md. Also check:

mergiraf languages | grep <extension>   # is the type registered?
git check-attr merge -- <path>          # should show: merge: mergiraf

Common causes:

Extension missing from ~/.gitattributes — regenerate after upgrade.
Parse failure on one of the three versions — mergiraf falls back silently.
Very large files (>1MB) skip structural merge.

Step 7 — Maintenance

mergiraf languages --gitattributes > ~/.gitattributes   # after upgrade

git rerere status              # what is currently tracked
git rerere diff                # pending resolution diffs
git rerere forget <path>       # forget a bad resolution
git rerere gc                  # clean old entries
ls .git/rr-cache/              # browse the resolution database

Special cases

Whitespace-only formatting changes

If one branch ran a formatter while the other modified content, mergiraf can produce more conflicts because AST positions shifted. Resolution: run the formatter on the merged result after resolving conflicts.

Unrecoverable state

If conflict state is unrecoverable, abort and start over:

git merge --abort        # or
git rebase --abort       # or
git cherry-pick --abort

/melt surfaces abort as an option; the user decides.