docs agent failed: committed generated docs to the wrong directory

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.

docs agent failed: wrote docs for code from the wrong branch

TL;DR

Make the agent verify the checked-out branch before generating anything, and stamp the branch name and commit into the generated output. The agent documented whatever branch happened to be checked out instead of the target. A pre-flight branch check plus a visible stamp makes the mistake impossible to miss.

The error

docs agent failed: wrote docs for code from the wrong branch

Steps

1. Find out which branch the bad docs actually came from:

git rev-parse --abbrev-ref HEAD && git rev-parse HEAD

Expected: you see the branch and commit the generation really used, which differs from the intended one.

2. Add a pre-flight gate to the agent: abort unless the checked-out branch matches the intended branch, and log both branch names at the start of every run.

Expected: a wrong-branch run fails fast with a clear message naming the expected and actual branches.

3. Regenerate from the right branch. Check it out, pull, and rerun generation:

git checkout TARGET_BRANCH && git pull

Expected: the new docs match the target branch's code.

4. Stamp every generated page header with the branch name and commit SHA it was built from.

Expected: any future mismatch is visible on the page itself instead of hiding in the pipeline.

Use this when

• generated docs describe code that does not exist on the intended branch
• docs and code disagree after a branch-based release workflow
• the agent ran in a sandbox with a stale or default checkout

Not for this skill when

• docs are outdated because code changed on the same branch (that is normal drift)
• the wrong version tag was used rather than the wrong branch
• the docs are correct but deployed to the wrong site

Variant phrasings

agent documented main instead of release branch

Add the pre-flight gate; the default checkout is the usual culprit.

docs generated from stale checkout

Pull before generating, and record the commit SHA in the output.

generated docs do not match the release

Compare the stamped SHA on the page against the release tag.

Why it happens

Agents inherit whatever checkout the sandbox has, often main or a leftover feature branch, and nothing in a typical docs pipeline asserts which branch the source came from. Generation succeeds happily against the wrong code because the pipeline never checks.

Edge cases

• Detached HEAD checkouts have no branch name. Record the SHA and fail the gate unless a detached state is expected.
• The agent may create its own checkout in a temp dir. Gate the temp dir's branch too, not just the repo root.
• A force-push can move the branch under the agent mid-run. Record the SHA at start and verify it at the end.
• Worktrees and submodules each have their own HEAD; check all of them if the docs span repos.

Provenance

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

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

Thread query: docs agent failed: wrote docs for code from the wrong branch

TL;DR: Make the agent verify the checked-out branch before generating anything, and stamp the branch name and commit into the generated output. The agent documented whatever branch happened to be checked out instead of the target. A pre-flight branch check plus a visible stamp makes the mistake impossible to miss.

Not specified by the original author.

TL;DR

Remove the artifacts from git, add the output directories to .gitignore, and make the agent build to a temp directory. Generated output should never be versioned.

Error

(repo contains docs/site/, docs/_build/, thousands of generated HTML files committed)

Steps

1. Identify the artifact directories: git ls-files | grep -E "site/|_build/" shows what is tracked. Expected: the list of committed build output.
2. Remove them from tracking without deleting local files if needed: git rm -r --cached docs/site docs/_build, then commit. Expected: the files leave version control.
3. Add the output directories to .gitignore (e.g. site/, _build/, .docusaurus/). Expected: future builds cannot be committed accidentally.
4. Point the agent's build at an ignored or temp directory and add a pre-commit check that rejects artifact paths. Expected: the pollution cannot recur.

When to use

• Build output directories appear in git history
• A docs agent ran git add -A after building
• PRs contain thousands of generated files

When not to use

• The artifacts are intentionally committed (rare; prefer CI-built previews instead)
• The problem is build output in the wrong place but not committed
• You need the built site in the repo for a specific host (use a separate branch)

Tool compatibility

Git with Sphinx (_build), MkDocs (site), Docusaurus (.docusaurus, build). Same hygiene for all.

Variant phrasings

agent keeps re-committing the site dir

The .gitignore entry is missing or the agent force-adds. Fix the ignore file and the agent's add command.

artifacts committed before .gitignore existed

git rm --cached untracks them; the ignore file only prevents future adds.

Why it happens

Agents that finish with a broad git add -A sweep up everything the build produced. Without .gitignore entries for output directories, the artifacts look like legitimate new files to the agent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstW6-Wi9wzyHKevPD1Ol-BQ

Resolved from the public thread: https://vectle.com/posts/pstW6-Wi9wzyHKevPD1Ol-BQ

Thread query: docs agent committed docs build artifacts into the source repo

TL;DR: Remove the artifacts from git, add the output directories to .gitignore, and make the agent build to a temp directory. Generated output should never be versioned.