resolving-merge-conflicts

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 8 处。

Entry SHA-256: 9d8114f8ef0b31f535a265fc05c364bd8cf2e2895a830040e06c22acb11f54b0

2. Why This Skill Is Clever

一句话核心机制

把冲突解决从“删掉标记让 Git 通过”升级为一条证据驱动的保意图流程：先还原双方动机，再按合并目标取舍，最后用项目检查验证并完成 Git 事务。

触发与边界

直接来源： frontmatter 把触发条件限定为正在进行中的 Git merge/rebase 冲突。它不适用于尚未开始的分支整合规划，也不授权借冲突之机重新设计功能。

支持性上下文： agents/openai.yaml 只提供展示名称和“Resolve merge and rebase conflicts”的短描述，没有增加执行规则。

解释： git、PR、issue/ticket、typecheck 等术语依赖具体仓库与协作平台。若宿主没有 PR 或 ticket 系统，仍可保留“追溯一手意图”的原则，但必须替换证据入口。

信息架构 / 执行顺序

1. 先观察 Git 历史、冲突文件和 merge/rebase 当前状态，避免在未知状态下修改。
2. 对每处冲突追溯 commit message、PR 与原始 issue/ticket，重建双方改动意图。
3. 逐个处理 hunk：优先兼容双方；无法兼容时，以本次合并的明确目标作裁决并记录取舍。
4. 禁止发明新行为，也禁止用 --abort 逃避完成。
5. 发现并按项目约定运行 typecheck、tests、format 等检查，修复合并造成的破坏。
6. 暂存、提交；若是 rebase，则继续直到所有提交完成变基。

最巧妙的设计点

1. 把“代码冲突”重新定义为“意图冲突”

“what the original intent was”

直接来源： 技能要求阅读提交、PR 与原始 issue/ticket。代码只是最终表现，真正需要协调的是两项改动背后的目标。这样能避免简单选择 ours 或 theirs 丢失业务意图。

2. 用分层裁决规则避免临场拍脑袋

“Preserve both intents where possible.”

“pick the one matching the merge's stated goal”

直接来源： 先尝试兼容双方，只有不兼容时才按合并目标选边。这是清晰的两级决策树，把“我更喜欢哪段代码”替换成可解释的裁决标准。

3. 允许损失，但要求留下取舍记录

“note the trade-off”

直接来源： 无法兼容时并不假装有完美答案，而是要求显式记录损失。它给评审者留下检查点，也为后续修复或回滚保留决策背景。

4. 用负约束锁住任务范围

“Do not invent new behaviour.”

直接来源： 冲突期间上下文复杂、测试可能暂时失败，最容易发生顺手重构或改变行为。强否定把工作限制在恢复已有意图，减少一次合并同时引入冲突修复和新需求的风险。

5. 完成定义跨越语法、语义与事务三层

“run them, typically typecheck, then tests, then format”

“Finish the merge/rebase.”

直接来源： 删除冲突标记只解决语法层；自动检查验证组合后的语义和质量；stage、commit、continue 则完成 Git 事务。三个层次缺一不可。

防失败机制与 trade-off

显式不变量（直接来源）：

• 必须检查当前 merge/rebase 状态、历史和冲突文件；
• 每处冲突都要追溯一手意图来源；
• 能兼容时保留双方意图，不能兼容时按合并目标裁决并记录取舍；
• 不得发明新行为；
• 必须解决，不能 --abort；
• 必须发现并运行项目自动检查，修复合并造成的破坏；
• 必须真正完成 merge/rebase。

解释与取舍： “始终解决、绝不 abort”能阻止智能体半途而废，却也是假设调用者已经决定完成此次整合。在发现错误分支、凭据泄漏或合并目标本身无效时，这一绝对规则可能不适合通用人工流程。typecheck → tests → format 只是典型顺序，不应覆盖仓库自己的检查约定。技能也没有规定如何处理缺失证据、冲突目标不明确、长时间测试或需要人类批准的取舍，这些仍是移植时要补的停止条件。

可迁移原则

1. 先恢复意图，再编辑结果。 对任何冲突都先找到拥有决策背景的一手材料。
2. 写出明确的裁决阶梯。 先兼容，后按共同目标选边，最后记录损失。
3. 用负约束阻止范围漂移。 明确这项修复绝不能顺手改变什么。
4. 把完成定义扩展到验证与事务关闭。 “文件能保存”不等于工作已经完成。
5. 尊重宿主项目的检查约定。 示例顺序可以参考，但仓库自身命令才是执行依据。

今日实践题

如果两个冲突分支分别优化性能与可读性，而且本次合并目标只写了“整合最新改动”，你会要求补充哪项一手证据，才能在无法兼容时作出可审计的选择？

Evidence note

本文关于触发条件、证据追溯、hunk 裁决、负约束、自动检查和完成 Git 流程的结论均来自所选 SKILL.md。agents/openai.yaml 仅用于确认展示描述，未作为原文或新增规则展示。关于三层完成定义、绝对禁止 abort 的适用风险、证据缺口与可移植性属于设计解释。