melt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/melt

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.

使用本技能通过结构化流程解决git merge、rebase或cherry-pick冲突：mergiraf → rerere → kdiff3。每个工具处理前一个工具无法解决的问题。

File IO routing

文件IO路由

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.

对于冲突标记或符号搜索、有限范围检查及手动编辑，请根据

code-intelligence-routing.md

直接调用选定的源代码后端。应用手动解决方案时，请遵循“搜索→最新有限范围读取→安全写入（避免覆盖未提交变更）”的流程。

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` .

阶段	工具	功能	运行时机
1	`mergiraf`	基于Tree-sitter对基准版本/本地版本/远程版本进行结构化合并。即使文本合并会冲突，独立新增内容也能干净合并。解析失败时回退到文本合并。	自动作为git合并驱动运行，或通过 `python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve` 手动触发。
2	`git rerere`	针对相同冲突特征，复用之前记录的人工解决方案。	在mergiraf处理之后运行，尤其适用于冲突反复出现的长期变基场景。
3	`kdiff3`	针对mergiraf和rerere无法解决的冲突，提供手动三路对比工具。	通过 `git mergetool` 启动。

Protocol

执行协议

0. Squash-residue check

0. squash残留检查

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

bash

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.

在生成冲突摘要前先运行此检查。若分支已被squash合并到基准分支，mergiraf无法提供帮助——请参考以下两种解决方案。

bash

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

若判定结果为

SQUASH-MERGED

，请将打印的两种解决方案原封不动展示给用户并终止流程。两种方案均不会自动应用——由用户选择并复制粘贴执行。参数：

```
--base
```
— 用于对比的基准分支（默认：
```
origin/main
```
）。
```
--branch
```
— 待检查分支（默认：当前分支）。
```
--json
```
— 用于脚本的结构化输出。

检测流程（优先级从高到低；仅在前序检测无结果时运行后续步骤）：

```
tree-match
```
— 遍历基准分支的提交，寻找与分支某一节点树结构完全匹配的提交。该提交即为分支对应节点之前所有提交的squash等价版本。支持离线运行，可处理分叉PR和文件重命名，也能处理分支在squash之后仍有新提交的情况（
```
local-synth
```
无法处理此场景）。始终优先运行。
```
gh-api
```
— 与tree-match并行运行。当tree-match的SHA与squash提交相关联时，用PR元数据（编号、URL、合并提交）增强判定结果；当tree-match无结果时，独立提供判定结果。
```
local-synth
```
— 根据HEAD的树结构合成一个虚拟squash提交，然后调用
```
git cherry
```
检查基准分支是否包含等价提交。仅当tree-match和gh-api均无结果时作为最后手段运行；无法区分被squash的提交和唯一提交。

判定结果语义：

```
SQUASH-MERGED
```
（
```
method=tree-match
```
或
```
tree-match+gh
```
）——最强信号；唯一提交列表为分支中匹配squash节点之后的所有提交。
```
SQUASH-MERGED
```
（
```
method=gh-api
```
）——当tree-match无结果但gh PR的SHA与分支提交重叠时的兜底判定。
```
SQUASH-MERGED
```
（
```
method=local-synth
```
）——仅离线检测；cherry-pick列表需人工审核。
```
not-detected
```
——继续执行后续冲突处理流程。
```
not-applicable
```
——当前处于基准分支。

检测器会按顺序输出两种解决方案：

[A] 合并（非破坏性）——
```
git merge <base>
```
。保留所有分支历史；已squash的提交会合并为无操作，仅真实冲突会暴露。当分支包含独有工作或唯一提交列表不确定时优先选择此方案。
[B] 重置并cherry-pick（破坏性）——
```
git reset --hard <base>
```
+
```
git cherry-pick <unique-shas>
```
。会重写分支历史，需要强制推送。当需要干净的线性历史且唯一提交列表完整时使用。

默认优先推荐[A]；仅当用户明确偏好线性历史工作流或唯一提交数量较少且已验证时才推荐[B]。

1. Diagnose

1. 诊断

Run the summary script next.

bash

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:

bash

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

接下来运行摘要脚本。

bash

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

默认输出简洁：每个文件一行元数据，加上最小化展示的冲突块。参数：

```
--json
```
— 用于脚本的结构化输出。
```
--verbose
```
— 面向人类的markdown格式视图。
```
--context N
```
— 冲突块周围的上下文行数（默认3行）。

如需原始git上下文：

bash

git log --merge --oneline    # 涉及合并的提交
git status                    # 冲突/暂存状态

2. Structural resolution

2. 结构化解决

For every file mergiraf supports, attempt structural merge:

bash

undefined

对所有mergiraf支持的文件，尝试结构化合并：

bash

undefined

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

Markdown输出及mergiraf调试日志

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`:

```bash
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:

bash

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

python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve --verbose


如需查看mergiraf对单个文件的处理结果但不修改工作区，使用`--debug`参数：

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

它会打印合并输出、日志及冲突标记数量的路径。使用

cat

diff

对比打印的路径；若合并输出干净，可应用该结果：

bash

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

3. Remaining conflicts

3. 剩余冲突处理

After the structural pass, check rerere first:

bash

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:

bash

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

After manual resolution, finish the interrupted operation:

bash

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.

结构化处理完成后，先检查rerere：

bash

git rerere status      # 已有记录解决方案的文件
git rerere diff        # 查看rerere将应用的变更

若rerere已应用，冲突已解决。否则进入手动工具：

bash

git mergetool          # 为每个冲突文件打开kdiff3
git mergetool <path>   # 或仅处理单个文件

手动解决后，完成中断的操作：

bash

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

完成标志：

git status

显示无

Unmerged paths

且无

<<<<<<<

标记残留。

关于本地/远程版本选择、锁文件处理、mergiraf调试及维护，请参考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.

脚本	用途	运行时机
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz detect-squash-residue`	检测分支是否已被squash合并，并输出合并和重置+cherry-pick两种解决方案	优先运行——若检测到则终止后续流程
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-summary`	生成带行号和上下文的结构化冲突摘要	残留检查之后
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz batch-resolve`	对所有冲突文件运行 `mergiraf merge`	支持的语言文件
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz conflict-pick`	按冲突块选择本地/远程版本	Shell、SQL及mergiraf无法解析的格式
`python3 ${CLAUDE_SKILL_DIR}/scripts/melt.pyz lockfile-resolve`	选择某一侧版本并重新生成锁文件	`Cargo.lock` 、 `package-lock.json` 等

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
```
.

推送或创建PR——移交至
```
gh
```
技能处理。
运行构建或测试——重新调用
```
/cook
```
或运行项目检查流程。
在
```
git add
```
暂存之外提交已解决文件——使用
```
commit
```
技能。
对合并结果进行架构评审——使用
```
/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.

```
mergiraf solve
```
参数混淆：使用
```
--stdout
```
/
```
-p
```
进行预览，而非
```
--output
```
。
mergiraf支持Markdown，但可能需要在
```
.gitattributes
```
中注册。
锁文件的结构化合并不等于有效锁文件——选择版本后务必重新生成。
本技能的所有脚本均支持zdiff3基准标记（
```
|||||||
```
）。
若在支持的文件类型中看到冲突，说明mergiraf作为驱动已运行过——当前看到的是未解决的残留冲突。

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.

冲突解决完成后，通过

../cheese/references/handoff-gate.md

中的共享移交网关提示下一步操作。在询问前，将检测到的中断操作及上游调用信息纳入上下文数据包。默认选项：

继续——调度当前操作的准确续行命令（
```
git merge --continue
```
、
```
git rebase --continue
```
或
```
git cherry-pick --continue
```
）。若已知触发技能的调用信息，git操作成功后返回原技能并携带原始上下文；否则终止并返回当前git状态。
重新运行检查流程——调度最初触发冲突的上游技能调用，使其质量检查流程在合并状态下运行。
终止——不调度任何操作；将工作区保留为暂存状态供用户检查。

/melt

绝不会在用户选择前自动继续流程。用户选择非终止选项后，立即执行选定的续行操作。",