docs agent failed: deleted hand-written docs while syncing generated pages
Recovers hand-written docs that a docs agent deleted during generated-page sync, and fences generated output so it cannot happen again. Use when a sync run removes hand-written markdown or pages you wrote by hand. Key trigger: git shows deleted docs files right after a docs agent sync.
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 pagesSteps
- List what was deleted: run
git status --shortright after the sync and note every D entry, orgit log --diff-filter=D --name-only -1if it was committed. Expected: a concrete list of deleted paths. - Restore them: for uncommitted deletions run
git restore -- [deleted-path]per file; for a committed bad sync, revert the commit. Expected:git status --shortshows the files back and the content matches the pre-sync version. - 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.
- 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.
- Rerun the sync and verify:
git status --shortshould 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