docs agent loop detected: repeatedly fixing the same broken link

docs agent loop detected: repeatedly fixing the same broken link

TL;DR

Stop the loop and fix the link at its source: correct the target, add a redirect, or remove the reference. The agent rewrites the link text each pass without changing where it points, so the checker fails identically every time. One real fix to the target beats infinite rewrites of the link.

The error

docs agent loop detected: repeatedly fixing the same broken link

Steps

1. Stop the agent and extract the exact failing URL and the page that links to it from the checker output.

Expected: you have the concrete link, not a category of links.

1. Decide the real fix once: does the target page exist under a new path (update the link), was it deleted (remove the link or point at a redirect), or is the checker wrong (allowlist that URL)?

Expected: one decision, made once, instead of another rewrite attempt.

1. Apply the fix and run the link checker on just that page.

Expected: the check passes for that link.

1. Add a loop guard: abort after 3 identical link-checker failures on the same URL and report the link instead of retrying.

Expected: future unfixable links surface fast with the URL named, instead of looping.

Use this when

• the agent rewrites the same link over and over and the check never passes
• the log shows identical failures on one URL across many attempts
• link text changes each pass but the target never does

Not for this skill when

• many different links are broken (that is a bulk fix job, not a loop)
• the links break because an external site went down (wait or allowlist)
• the checker itself is misconfigured for the whole site

Variant phrasings

agent stuck fixing one broken link

Extract the URL, decide the target fix once, then guard the loop.

link checker loop never resolves

The agent is editing the symptom. Fix the target or allowlist the URL.

same link fails after every agent fix

Check whether the target page exists at all before the next rewrite.

Why it happens

The agent edits the symptom (the link text) while the disease (target missing, moved, or checker misconfigured) is untouched. Every attempt fails the same way because nothing about the actual failure changed, and there is no abort on repeated identical failures.

Edge cases

• Anchor links break when headings get reworded. Check that the anchor exists on the target page, not just that the page loads.
• Checkers that do not run scripting will flag script-rendered pages as broken. Verify in a real browser before rewriting the link.
• Redirect chains can exceed the checker's hop limit while working fine for users. Raise the hop limit or link straight to the final URL.
• Case-sensitive paths on Linux versus case-insensitive local filesystems cause links that pass locally and fail in CI. Match the deployed case exactly.

Provenance

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