agentleFS
nobodyohm-webnobodyohm-web/Thot/skills/autonomous-ai-agents/merge-reconciler/SKILL.md

merge-reconciler

Skill0 starsChanged 3 months agoMITView on GitHub

Neutral third-party resolution of agent merge conflicts.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do NOT use for conflicts within a single agent's own work, or for trivial lockfile/generated-file conflicts (regenerate those instead).

    line 29
  2. Very specific:

    Run via terminal: git status (confirm the conflicted state and list conflicted files), git merge-base <A> <B>, then for each side git log …

    line 74
  3. Distinctive:

    If a single hunk contains multiple independent decisions (e.g., new logic that combines cleanly PLUS a styling/rounding choice both sides …

    line 91
  4. Distinctive:

    Never favor the side that spawned you.

    line 107
  5. Very specific:

    Run the project's build/tests via terminal.

    line 117
  6. Distinctive:

    Self-favoring: if you were spawned by one of the conflicting agents, you are structurally biased — state this and weigh the other side's …

    line 135
  7. Distinctive:

    Missing intents: commit messages alone can be thin.

    line 144
  8. Very specific:

    No conflict markers remain (search_files pattern <<<<<<<).

    line 155

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Merge Reconciler

Resolve a git merge conflict between two AGENTS' branches as an impartial third party. Agents resolving conflicts against a peer's work reliably either overwrite the peer or abandon their own change — they lack the peer's context and are biased toward their own side. This skill is the fix: a neutral reconciler that receives both diffs plus both sides' stated intents and produces a merged result, like a merge-queue arbiter.

When to Use

  • Two agent branches/worktrees collide during a parallel campaign (kanban engineering pipeline, parallel-PR wave, multi-worktree refactor).
  • git merge or git rebase halts on conflicts between two agents' work and neither original agent should self-adjudicate.
  • Do NOT use for conflicts within a single agent's own work, or for trivial lockfile/generated-file conflicts (regenerate those instead).

Prerequisites

  • A repo checkout containing the halted merge, or the two branch names plus permission to run the merge yourself.
  • Both sides' intent sources: kanban completion summaries (terminal running hermes kanban show <task-id>), PR bodies, or at minimum each branch's commit messages.
  • The project's build/test command, if one exists.

How to Run

Standalone — a human (or agent) invokes this skill inside the conflicted repo: load the skill, then follow the Procedure top to bottom.

Spawned neutral agent — the preferred shape in multi-agent campaigns:

  • delegate_task: spawn a subagent whose task message contains the repo path, both branch names, and both sides' intent summaries verbatim, plus an instruction to follow this skill.
  • Kanban-native: create a reconciliation card assigned to a third profile (not either worker's profile) with BOTH conflicted cards linked as parents — kanban_create(title="reconcile branch-a x branch-b", assignee="reconciler", parents=["t_a", "t_b"]). The parent links carry both sides' completion summaries into the reconciler's context automatically; the card body should name the repo path and the two branches.

Quick Reference

Hunk classDefinitionResolution
disjoint-intentThe two changes serve different goals and can coexistCombine both
same-question-different-answerBoth sides answered one design question differentlyPick ONE per stated intents; surface the decision
supersededOne side's premise no longer holds after the other's changeKeep the surviving side; note why

Impartiality contract: never favor the side that spawned you; touch ONLY conflicted regions (no drive-by edits); every design-question pick must appear explicitly in the hand-back summary.

Procedure

1. Gather both sides

  • Run via terminal: git status (confirm the conflicted state and list conflicted files), git merge-base <A> <B>, then for each side git log --oneline <base>..<side> and git diff <base>..<side> -- <file> for every conflicted file. In a halted merge, HEAD is one side and MERGE_HEAD is the other.
  • Collect each side's intent: hermes kanban show <task-id> for completion summaries/metadata, or the PR body, or the commit messages from the log above. Write down one sentence of intent per side before touching any file.
  • Done when: you can state both intents in your own words and have both diffs for every conflicted file.

2. Classify every conflicted hunk

  • Open each conflicted file with read_file and locate each <<<<<<</=======/>>>>>>> block.
  • Assign each hunk exactly one class from the Quick Reference table, judging by the stated intents — not by which change looks nicer.
  • If a single hunk contains multiple independent decisions (e.g., new logic that combines cleanly PLUS a styling/rounding choice both sides answered differently), decompose it into sub-decisions and classify each one.
  • A single file often mixes classes: one hunk may be a design collision while a neighboring hunk is disjoint. Classify per hunk, not per file.
  • Done when: every hunk has a written class and a one-line rationale.

3. Resolve under the impartiality contract

  • Edit each hunk with patch (or write_file for whole-file rewrites):
    • disjoint-intent → merge both changes so each intent is fully served.
    • same-question-different-answer → pick the answer that best serves the STATED intents (e.g., an intent of "strict validation" beats "quick default" if the task required correctness). Never split the difference into a hybrid neither side asked for.
    • superseded → keep the surviving side; delete the dead premise.
  • Never favor the side that spawned you. If intents genuinely tie, escalate (block the kanban card / report back) rather than guess.
  • Change nothing outside conflict markers — no formatting, renames, or opportunistic fixes.
  • git add each resolved file via terminal.
  • Done when: search_files finds no <<<<<<< markers in the repo and every resolved file is staged.

4. Verify

  • Run the project's build/tests via terminal; at minimum import/execute the touched modules. Both intents must be observable in the merged behavior (e.g., side A's new semantics AND side B's disjoint addition both present).
  • Complete the merge: git commit (the default merge message plus a body listing hunk decisions is fine).
  • Done when: verification passes and the merge commit exists.

5. Hand back

  • Produce a completion summary naming EVERY hunk decision: file:lines — class — which side(s) kept — rationale. For every same-question-different-answer hunk, state the design question and the answer you picked so a human can veto it — never bury a design call.
  • Kanban: kanban_complete(summary=...). Standalone: print the summary.
  • Done when: the summary is delivered and lists all hunks.

Pitfalls

  • Self-favoring: if you were spawned by one of the conflicting agents, you are structurally biased — state this and weigh the other side's intent deliberately. Prefer the third-profile shape so this never arises.
  • Splitting the difference on a design collision produces a hybrid nobody designed; pick one answer and surface it.
  • Per-file classification: files usually mix hunk classes; classifying a whole file as one class silently drops a disjoint change.
  • Drive-by edits make the merge unreviewable and steal decisions from the original agents.
  • Missing intents: commit messages alone can be thin; prefer kanban completion summaries or PR bodies. If neither side's intent is recoverable, escalate instead of guessing.
  • Repeat offenders: repeated conflicts on the SAME file across rounds are a hotspot signal, not routine reconciliation work — flag it (e.g. a hotspot: <path> — <reason> kanban comment) so the orchestrator decomposes that file, rather than serially reconciling every new collision on it.

Verification

  • git status shows a clean tree on the target branch with a merge commit.
  • No conflict markers remain (search_files pattern <<<<<<<).
  • Build/tests pass; both sides' intents are demonstrably present or the dropped one is explicitly named in the summary.
  • The hand-back summary enumerates every hunk with class and rationale.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.