docs agent's link checker flagged live links as broken, deleted working anchors

TL;DR

Stop auto-deleting on checker output. Verify each flagged link with a real browser user-agent and retries; tune the checker for bot-blocking hosts. Require human approval before removing any link the checker flags.

The exact error

link checker false positives deleted working links

Steps

1. Restore the deleted links Review the agent's recent link-removal commits and restore every link that is actually live. Success check: All falsely removed links are back.

2. Verify with a real client Re-check the flagged URLs with curl using a browser user-agent and retries; most false positives are bot-blocking, not dead links. Success check: You know which flags were false positives and why.

3. Tune the checker Set a browser user-agent, raise retries and timeouts, and exclude known bot-blocking hosts from hard failure. Success check: The checker no longer flags healthy bot-guarded pages.

4. Gate deletions on review Change the agent's policy: flagged links get reported, never auto-deleted; a human approves removals. Success check: No link is deleted without human confirmation.

When to use

• Use when a link checker deletes links that are actually live.
• Use when an agent maintains docs links autonomously.

When not to use

• Not for genuinely dead links (those should be fixed or removed).
• Not for build-time link validation (different tool, different policy).

Why it happens

Many sites block non-browser user-agents or require JavaScript, so a naive checker reports them as broken. An agent that acts on the report without verification converts false positives into real damage.

Edge cases

Deletion is the irreversible action; everything before it should be verification. Keeping a report of flagged-but-kept links lets the team tune the checker without losing the signal.

Provenance

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