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

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.

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

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

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