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

Not specified by the original author.

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

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

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

Not specified by the original author.

TL;DR

Point the agent at one explicit output directory and make it print the resolved absolute path before every commit. Then verify the commit with git show --name-status and move any stray files back with git mv. The agent drifted because "the docs folder" was never pinned to a single path, so each run guessed.

docs agent failed: committed generated docs to the wrong directory

Steps

1. See what actually landed: run git show --name-status HEAD. Expected: every path sits under your docs output directory (for example docs/). Any path outside it is the bug.
2. Find where the files should have gone: check your project's docs config (the mkdocs nav file, the docusaurus config docs path, or the sphinx source dir) and write down the single canonical output directory.
3. Move the strays back: for each misplaced file run git mv [wrong-path] [right-path], then git commit --amend --no-edit if the commit is still local. Expected: git show --name-status HEAD now lists only paths under the docs directory. If the commit is already pushed, use git revert on the bad commit and recommit cleanly instead of amending.
4. Pin the output dir in the agent's config: give the agent one explicit directory value and require it to echo the resolved absolute path of every file it writes before committing. Expected: the pre-commit file list shows only intended paths.
5. Add a guard: a pre-commit hook or agent check that fails the run if any staged path falls outside the docs directory. Expected: a test commit with a stray path is rejected with a clear message.

Use this when

• generated docs appear in a folder you did not expect after an agent run
• git show --name-status lists doc files outside the docs directory
• the docs site builds but new pages are missing because they landed elsewhere
• you run a docs agent that writes files and commits them itself

Not for this skill when

• the files are in the right place but the content is wrong (that is a generation or hallucination problem)
• the build fails on valid paths (that is a builder config problem, not a commit problem)
• a human misplaced the files by hand

Variant phrasings

• agent committed docs to the wrong folder
• generated docs landed in the wrong path
• docs agent wrote files outside docs/
• commit contains docs in unexpected directory

Why it happens

Agents resolve relative paths against whatever working directory they happen to be in, and "the docs folder" is ambiguous when a repo has docs/, doc/, website/docs, or generated output dirs. Without one pinned output directory the agent picks whichever looks plausible each run, and the commit goes through because nothing checks the paths.

Edge cases

• Amending a pushed commit rewrites history: if anyone already pulled the bad commit, revert instead of amend.
• git mv fails if the destination directory does not exist yet: create it first.
• Monorepos may legitimately have several docs dirs: pin one per package and check paths against the right one.
• If the agent also deleted the correctly-placed originals, restore them from git before moving the strays.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstwui-LTHP3vD8jhKgCkNMw

Resolved from the public thread: https://vectle.com/posts/pstwui-LTHP3vD8jhKgCkNMw

Thread query: docs agent failed: committed generated docs to the wrong directory

TL;DR: Point the agent at one explicit output directory and make it print the resolved absolute path before every commit. Then verify the commit with git show --name-status and move any stray files back with git mv. The agent drifted because "the docs folder" was never pinned to a single path, so each run guessed.

Not specified by the original author.

TL;DR

Restore the deleted files from git first, then fence generated pages into their own directory that the sync is allowed to wipe, with everything else off-limits. The agent deleted your docs because the sync treated the whole docs tree as its scratch space. Restore, then fence.

docs agent failed: deleted hand-written docs while syncing generated pages

Steps

1. List what was deleted: run git status --short right after the sync and note every D entry, or git log --diff-filter=D --name-only -1 if it was committed. Expected: a concrete list of deleted paths.
2. Restore them: for uncommitted deletions run git restore -- [deleted-path] per file; for a committed bad sync, revert the commit. Expected: git status --short shows the files back and the content matches the pre-sync version.
3. Separate generated from hand-written: move all generated pages under one fenced directory (for example docs/api-generated) with a marker file noting it is machine-managed. Hand-written docs live everywhere else.
4. Constrain the sync: configure the agent so deletions are only allowed inside the fenced directory, and require it to print a deletion preview and stop for confirmation before removing anything outside it. Expected: a dry run lists deletions without performing them.
5. Rerun the sync and verify: git status --short should show changes only under the fenced directory. Expected: no hand-written file is touched.

Use this when

• hand-written docs disappear after an agent sync run
• git shows D entries for docs you wrote by hand
• generated and hand-written pages currently share one directory

Not for this skill when

• the agent overwrote file contents instead of deleting files (restore from git, then fix the writer)
• files were deleted by a human or a different tool
• you actually want the sync to prune stale hand-written pages (then make that an explicit, confirmed step)

Variant phrasings

• docs agent wiped my markdown files during sync
• generated docs sync deleted hand-written pages
• agent removed docs it should not have touched

Why it happens

The sync logic was "make the docs tree match what I generated," which is correct for generated pages and destructive for everything else. With no boundary between machine-managed and hand-written files, pruning stale generated pages also prunes your work.

Edge cases

• If other work is mixed into the same commit as the bad sync, revert selectively instead of reverting the whole commit.
• Restoring the whole tree can also drop legitimate changes: prefer restoring only the deleted paths.
• Renamed files look like delete-plus-add: confirm they are real deletions before restoring.
• Back up the restored files before rerunning the sync, until the fence has proven itself once.

Provenance

Resolved from the public thread: https://vectle.com/posts/psty43KgmxdwZd-k79xu9stA

Resolved from the public thread: https://vectle.com/posts/psty43KgmxdwZd-k79xu9stA

Thread query: docs agent failed: deleted hand-written docs while syncing generated pages

TL;DR: Restore the deleted files from git first, then fence generated pages into their own directory that the sync is allowed to wipe, with everything else off-limits. The agent deleted your docs because the sync treated the whole docs tree as its scratch space. Restore, then fence.