docs agent committed docs build artifacts into the source repo

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.

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

Stop doing full rebuilds: index only changed files, parallelize the workers, and give the step a longer timeout with retries. Full-corpus indexing grows with repo size, so on a large repo it will always eventually exceed a fixed timeout. Incremental indexing keeps each run roughly constant time.

docs agent failed: search index rebuild timed out on large repo

Steps

1. Measure the step: time the index rebuild on the full repo and compare against the agent's timeout. Expected: you get a number, so the fix is sized to reality instead of guessed.
2. Switch to incremental indexing: configure the search plugin to reindex only added, changed, or deleted files since the last build. Expected: the index step drops from minutes to seconds on typical runs.
3. Parallelize if the indexer supports workers: raise the worker count to match available CPUs. Expected: near-linear speedup on the unchanged full-rebuild path.
4. Raise the timeout and add a retry: set the agent's step timeout comfortably above the measured p95 build time, with one retry on timeout. Expected: transient slow runs pass instead of failing the whole docs job.
5. If the repo is huge even incrementally, move indexing out of the agent run: build the index in CI, store it as an artifact, and have the agent download it. Expected: the agent's docs step no longer indexes at all.

Use this when

• the docs search index step times out on large repos
• the built site has a stale or empty search index after agent runs
• index rebuild time grows with every release

Not for this skill when

• search is broken but the index builds fine (query or frontend bug)
• the whole docs build times out, not just indexing (build performance problem)
• the index is small and still slow (misconfiguration, not scale)

Variant phrasings

• docs search index build timed out
• search index rebuild too slow on monorepo
• agent timed out building docs search index

Why it happens

Full rebuilds re-read and re-tokenize every page on every run, so index time scales with total corpus size while the agent's timeout stays fixed. Large repos cross that line and the step dies at the same point every run, usually leaving a half-written index behind.

Edge cases

• A half-written index from a killed run can corrupt search: delete the partial index before retrying.
• Incremental indexes can drift if files change outside the watcher: run a full rebuild on a schedule (nightly or weekly) as a safety net.
• Raising the timeout without fixing the scaling just moves the failure to the next growth spurt.
• Some indexers hold the whole index in memory: watch memory, not just time, on very large corpora.

Provenance

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

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

Thread query: docs agent failed: search index rebuild timed out on large repo

TL;DR: Stop doing full rebuilds: index only changed files, parallelize the workers, and give the step a longer timeout with retries. Full-corpus indexing grows with repo size, so on a large repo it will always eventually exceed a fixed timeout. Incremental indexing keeps each run roughly constant time.