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.

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.