docs agent failed to detect file renames, docs reference deleted paths

docs agent failed to detect file renames, docs reference deleted paths

TL;DR

Rerun the sync with rename detection turned on and add a dead-link check over the docs. The agent compared file lists instead of following renames, so every moved file looked deleted and every link to it now 404s. Rename-aware diffing plus a link checker catches this whole class of drift.

The error

docs agent failed to detect file renames, docs reference deleted paths

Steps

1. List what actually moved, with rename detection on:

git log --diff-filter=R --name-status -20

Expected: you see old-path to new-path pairs for recent renames instead of separate delete and add entries.

2. Find every docs reference to the old paths. Search the docs tree for the old filenames and URLs.

Expected: a concrete list of stale references, each tied to a rename pair from step 1.

3. Update the references to the new paths. If old URLs must keep working for external readers, add redirect or alias pages for them.

Expected: no remaining references to deleted paths in the docs source.

4. Add a link checker to the docs build or CI so the next rename breaks the build instead of shipping 404s. Verify it works by temporarily breaking one link.

Expected: a deliberately broken link fails the check, proving the guard is live.

Use this when

• docs link to files that were renamed in a refactor
• a link checker reports 404s on paths that exist under new names
• the sync reported files as deleted that were actually moved

Not for this skill when

• links are broken for other reasons like typos or external sites being down
• the agent already handled the renames correctly
• the files were truly deleted, not renamed (update or remove the links)

Variant phrasings

docs 404 after file rename

Map old to new with rename-aware git log, then sweep the docs for old paths.

moved files not detected in docs sync

Turn on rename detection in whatever diff the sync uses; plain add-plus-delete diffing cannot connect the two sides.

link checker failing after refactor

Fix the references first, then keep the checker as the permanent guard.

Why it happens

Rename detection is heuristic and often off by default. A naive sync diffs file lists, sees a delete plus an add, and never connects them. Every link pointing at the old path then 404s, and nothing in the pipeline notices until a reader or a checker trips over it.

Edge cases

• Heavily rewritten files may not register as renames even with detection on. Lower the similarity threshold or handle those pairs by hand.
• Case-only renames look like no-ops on case-insensitive filesystems but break on Linux CI. Normalize case in the checks.
• External sites linking to old URLs need redirects, not just fixed internal links.
• Directory renames produce many pairs at once. Handle the directory mapping as one rule instead of fixing files one by one.

Provenance

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