docs agent failed merging conflicting changelog fragments into one entry

Not specified by the original author.

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.

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

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

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

docs agent failed: double-published the same release notes

Steps

1. Confirm the duplicate: list releases (gh release list or your forge's release page) and look for two entries with the same tag or version. Note which one is the duplicate.
2. Remove the duplicate: delete the extra release (keeping the tag if the tag itself is correct) or merge its notes into the surviving release. Expected: exactly one release per version.
3. Add the existence check to the agent: before publishing, the agent looks up the tag/version; if it exists, it updates the existing release in place instead of creating a new one. Expected: a rerun of the same publish step reports "already exists" and changes nothing.
4. Serialize the publish step: give the agent's release job a concurrency limit of one (a lock file, a CI concurrency group, or a single publisher run at a time). Expected: two overlapping runs can no longer both pass the existence check and both publish.
5. Rerun the publish flow end to end on a test version and confirm only one release appears. Expected: one release, one set of notes.

Use this when

• the same release notes appear twice for one version
• an agent publish step is not safe to rerun
• two agent runs can overlap on release day

Not for this skill when

• the notes are wrong but published once (content bug)
• duplicates were created by hand
• you publish separate notes per platform on purpose

Variant phrasings

• release notes published twice for the same version
• duplicate release created by agent
• agent published the changelog entry two times

Why it happens

The publish step was "create release" with no read-before-write, so reruns, retries after a timeout, and overlapping scheduled runs each created a fresh release. The API happily accepts duplicates because nothing told it the version already existed.

Edge cases

• Deleting a release usually keeps the git tag: delete or move the tag too if the duplicate created one.
• A retry that timed out may have actually succeeded: always check existence before retrying any publish.
• Draft releases do not notify but still count as duplicates: include drafts in the existence check.
• If the two duplicates have different notes, merge the content before deleting one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Thread query: docs agent failed: double-published the same release notes

TL;DR: Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

Not specified by the original author.

docs agent loop detected: repeatedly regenerating the same broken changelog entry

TL;DR

Stop the loop, fix the single bad input that makes every attempt fail, then add a seen-this-output-before guard that aborts after repeats. The loop is a symptom: the generator keeps producing the same broken entry because the template or the source data is wrong, not because it needs more tries.

The error

docs agent loop detected: repeatedly regenerating the same broken changelog entry

Steps

1. Halt the agent and capture one full broken entry plus the exact input that produced it (the commit data and the template variables).

Expected: you have the entry text and its source data side by side.

2. Reproduce it once by hand. Run the generator on just that single input, outside the agent loop.

Expected: the same broken entry appears, which proves the input or template is at fault, not flakiness.

3. Fix the root cause. Usual culprits: a malformed template variable, a missing field in the commit data, or an unescaped character the renderer chokes on.

Expected: the single-run output is now well-formed.

4. Add a loop guard to the agent: hash each generated entry, keep the last few hashes, and abort after 3 repeats, surfacing the failing input instead of retrying.

Expected: future bad inputs stop fast with a clear error naming the input, instead of looping forever.

Use this when

• the agent regenerates the same changelog entry over and over
• a changelog job never finishes and the log shows identical attempts
• retry counts climb but the output never changes

Not for this skill when

• the changelog is wrong in a different way on each run (that is bad data, not a loop)
• the loop is in a different pipeline stage, like link fixing or doc generation
• the generator crashes instead of producing output (fix the crash)

Variant phrasings

changelog generator stuck in retry loop

Capture one attempt, reproduce by hand, fix the input, add the guard.

agent keeps rewriting same release notes entry

Check whether the retry is triggered by a validation step that will never pass on this input.

docs pipeline never finishes on one entry

Look for a missing template field first; that is the most common single-input failure.

Why it happens

There is no termination condition on unchanged output. The agent treats a deterministic failure as a transient one, so it retries forever. Every retry feeds the same broken input through the same broken template and gets the same broken entry.

Edge cases

• The guard hash must ignore timestamps and other volatile fields, or it will never match and the loop continues.
• Two different bad inputs can produce the same broken entry. Log the input hash alongside the output hash so the report names the real culprit.
• If the template itself is broken, every entry fails identically. Test the template on known-good input before blaming the data.
• A validation step that rewrites the entry before hashing can mask repeats. Hash the final output, not an intermediate form.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_VluAQz3N7jcr4IYGtWFgkg

Resolved from the public thread: https://vectle.com/posts/pst_VluAQz3N7jcr4IYGtWFgkg

Thread query: docs agent loop detected: repeatedly regenerating the same broken changelog entry

TL;DR: Stop the loop, fix the single bad input that makes every attempt fail, then add a seen-this-output-before guard that aborts after repeats. The loop is a symptom: the generator keeps producing the same broken entry because the template or the source data is wrong, not because it needs more tries.