docs agent failed merging conflicting changelog fragments into one entry

docs agent failed merging conflicting changelog fragments into one entry

TL;DR

Keep both fragments' content, dedupe the overlap, and sort by change type instead of picking a winner. The merge failed because two fragments described the same release differently and the agent tried to choose one. Union-with-dedupe preserves information and never loses an entry.

The error

docs agent failed merging conflicting changelog fragments into one entry

Steps

1. Lay both fragments side by side and mark which lines say the same thing in different words.

Expected: you have the overlap mapped and can see exactly what is unique to each fragment.

1. Merge by union. Keep every unique change line from both fragments and drop exact duplicates.

Expected: no change mentioned in either fragment is lost in the merged entry.

1. Re-sort the merged entry by change type (breaking changes, features, fixes) and normalize the wording to one voice.

Expected: one coherent entry that reads like it was written once.

1. Teach the agent this merge rule and add a conflict fixture to its tests: two overlapping fragments must merge to their union.

Expected: the next conflict merges cleanly instead of failing or dropping entries.

Use this when

• changelog fragment merging fails or silently drops entries
• two fragments describe the same release in different words
• towncrier-style or changie-style fragment workflows produce conflicts

Not for this skill when

• the fragments are exact duplicates (plain dedupe handles that, no conflict)
• the merge fails because a fragment file is malformed
• fragments belong to different releases (sort by release first)

Variant phrasings

changelog merge conflict between fragments

Apply union-with-dedupe rather than picking one side.

duplicate changelog entries after merge

The dedupe step is missing or compares raw text without normalizing whitespace.

fragment merge dropped an entry

Check the merge rule: anything not recognized as a duplicate must be kept.

Why it happens

Fragment-based changelogs let parallel work describe the same release independently. Without a union rule, the merger treats overlapping descriptions as a conflict it cannot resolve, so it either errors out or picks one fragment and discards the other.

Edge cases

• Contradictory fragments (one says breaking, one says minor) need a human call. Flag them instead of auto-picking.
• Fragments for different releases landing in the same file are not conflicts. Sort by release before merging.
• Whitespace-only differences should not count as conflicts. Normalize before comparing.
• A fragment that renames a change another fragment describes can look like two changes. Read for meaning, not just string equality.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_XyT-VWoqvTIJGWqZK-OjtQ