agentleFS
Sign inStart free
cashew-labscashew-labs/libretto/.agents/skills/fix-merge-conflicts/SKILL.md

fix-merge-conflicts

Skill898 starsChanged 3 months agoMITView on GitHub

Resolve Git merge, rebase, or cherry-pick conflicts by preserving intent from both sides. Use when unmerged paths or conflict markers are present, especially when you must inspect the PR title and description tied to conflicting commits before choosing a resolution.

We split this skill into the rules it gives an agent

26 rules. 0 are common, 23 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 23

    Distinctive

    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. Very specific:

    Run preflight conflict detection.

    line 10
  2. Distinctive:

    Read PR title and description to extract intent.

    line 13
  3. Very specific:

    If there are no active unmerged paths, proactively merge latest origin/main to surface conflicts:

    line 21
  4. Very specific:

    If git diff --name-only --diff-filter=U returns files, skip auto-merge and continue to conflict analysis.

    line 30
  5. Distinctive:

    If it returns nothing, run:

    line 31
  6. Distinctive:

    If conflicts now exist, continue with the rest of this workflow.

    line 44
  7. Distinctive:

    If still no conflicts, report that no merge conflicts were detected and stop.

    line 45
  8. Distinctive:

    Use git log --left-right --merge as the starting set of commits that influenced the conflicted hunks.

    line 57
  9. Distinctive:

    Prefer GitHub metadata when available.

    line 61
  10. Distinctive:

    If no associated PR is found, fall back to git show --stat COMMIT_SHA and commit message context.

    line 72
  11. Distinctive:

    Write a short intent summary per side before editing code.

    line 82
  12. Distinctive:

    Before finalizing any hunk where intents conflict, notify the user and ask for direction.

    line 86
  13. Distinctive:

    Treat these as divergence signals:

    line 88
  14. Distinctive:

    When divergence is detected:

    line 94
  15. Distinctive:

    Ask one explicit resolution question.

    line 98
  16. Distinctive:

    Wait for user response before applying the final hunk resolution.

    line 99
  17. Distinctive:

    If the user chooses one side, preserve that side and salvage any non-conflicting behavior from the other side.

    line 110
  18. Distinctive:

    If the user requests a hybrid, restate the hybrid rule before applying edits.

    line 111
  19. Distinctive:

    Keep both behaviors if they are compatible.

    line 118
  20. Distinctive:

    If incompatible, keep repository invariants and adapt the losing side's goal into a safe equivalent.

    line 119
  21. Distinctive:

    Never silently drop behavior that was explicitly called out in a PR description.

    line 120
  22. Distinctive:

    Avoid resolving by "take ours/theirs" unless the PR intent proves one side is obsolete.

    line 122
  23. Distinctive:

    Run focused checks that cover touched behavior.

    line 126
  24. Distinctive:

    Run broader checks when conflict scope is wide.

    line 133
  25. Distinctive:

    Follow-up risk or test gap, if any

    line 142
  26. Distinctive:

    If intent is ambiguous after reading PR metadata, ask one specific question before finalizing.

    line 144

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “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

Resolve conflicts by intent, not by line order.

Workflow

  1. Run preflight conflict detection. If no local merge/rebase/cherry-pick conflicts are present, automatically fetch and merge origin/main.
  2. Identify conflicted files and candidate commits.
  3. Map each conflicting commit to its PR.
  4. Read PR title and description to extract intent.
  5. Detect intent divergence and request user intervention.
  6. Resolve conflicts to preserve both intents when compatible.
  7. Validate behavior with targeted checks.
  8. Summarize decisions and any tradeoffs.

0) Preflight: Ensure a Conflict Exists

If there are no active unmerged paths, proactively merge latest origin/main to surface conflicts:

git status --porcelain
git diff --name-only --diff-filter=U

Decision rule:

  • If git diff --name-only --diff-filter=U returns files, skip auto-merge and continue to conflict analysis.
  • If it returns nothing, run:
git fetch origin
git merge origin/main

Then re-check:

git diff --name-only --diff-filter=U
  • If conflicts now exist, continue with the rest of this workflow.
  • If still no conflicts, report that no merge conflicts were detected and stop.

1) Identify Conflict Scope

Run:

git status --porcelain
git diff --name-only --diff-filter=U
git log --left-right --merge --oneline

Use git log --left-right --merge as the starting set of commits that influenced the conflicted hunks.

2) Map Commits to PRs

Prefer GitHub metadata when available.

  1. Parse owner/repo from origin.
  2. For each conflicting commit SHA, query associated PRs.
gh api graphql \
  -f query='query($owner:String!,$repo:String!,$sha:GitObjectID!){repository(owner:$owner,name:$repo){object(oid:$sha){... on Commit{associatedPullRequests(first:5){nodes{number title body url mergedAt baseRefName headRefName}}}}}}' \
  -F owner=OWNER -F repo=REPO -F sha=COMMIT_SHA

If no associated PR is found, fall back to git show --stat COMMIT_SHA and commit message context.

3) Extract Intent

For each relevant PR, capture:

  • Goal stated in title
  • Constraints, caveats, or behavioral expectations from description
  • Any explicitly non-goals

Write a short intent summary per side before editing code.

4) Divergence Checkpoint (User Intervention Required)

Before finalizing any hunk where intents conflict, notify the user and ask for direction.

Treat these as divergence signals:

  • Both sides change the same behavior with incompatible outcomes
  • One side explicitly rejects behavior the other side introduces
  • Either PR description states a constraint that the other side would violate

When divergence is detected:

  1. Pause editing for that hunk.
  2. Provide a short comparison of intent A vs intent B.
  3. Ask one explicit resolution question.
  4. Wait for user response before applying the final hunk resolution.

Question format:

Intent divergence detected in <file>:<hunk>.
Option A (PR #X): <one-line intent>
Option B (PR #Y): <one-line intent>
Which intent should be primary for this hunk?

If the user chooses one side, preserve that side and salvage any non-conflicting behavior from the other side. If the user requests a hybrid, restate the hybrid rule before applying edits.

5) Resolve by Preserving Intent

For each conflict hunk:

  1. Explain what each side is trying to preserve.
  2. Keep both behaviors if they are compatible.
  3. If incompatible, keep repository invariants and adapt the losing side's goal into a safe equivalent.
  4. Never silently drop behavior that was explicitly called out in a PR description.

Avoid resolving by "take ours/theirs" unless the PR intent proves one side is obsolete.

6) Validate

Run focused checks that cover touched behavior. In this repository, prefer:

pnpm --filter libretto-cli type-check
pnpm --filter libretto-cli test -- <relevant-test-file>

Run broader checks when conflict scope is wide.

7) Report

Provide a concise summary:

  • Files resolved
  • PR intents preserved
  • Any intentional compromise and why
  • Follow-up risk or test gap, if any

If intent is ambiguous after reading PR metadata, ask one specific question before finalizing.

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.

Check your setup, free