docs agent failed: docs preview deploy overwrote the staging branch

Not specified by the original author.

TL;DR

Restore the staging branch from its pre-deploy state, then change preview deploys to target ephemeral preview URLs instead of branches. Protect the staging branch so the agent's deploy role cannot push to it.

The exact error

docs preview deploy overwrote staging branch

Steps

1. Recover staging Reset the staging branch to its last good commit from the reflog or the remote's history. Success check: Staging is back to its pre-deploy state.

2. Move previews off branches Point preview deploys at ephemeral preview URLs or a dedicated previews directory, never at a shared branch. Success check: Previews no longer touch shared branches.

3. Protect the branch Enable branch protection on staging denying pushes from the agent's deploy role. Success check: The agent physically cannot overwrite staging again.

4. Verify the deploy flow Run a preview deploy and confirm it lands on the preview target while staging is untouched. Success check: Previews work and staging is safe.

When to use

• Use when an agent's deploy step writes to the wrong branch.
• Use when designing deploy permissions for doc agents.

When not to use

• Not for content errors in a correctly targeted deploy.
• Not for preview deploys that fail to build.

Why it happens

Agents treat branches as generic deploy targets; without protection, a misconfigured target overwrites whatever branch is named. Staging branches are especially vulnerable because they look like natural preview targets.

Edge cases

Branch protection is the durable fix; getting the target right in config is necessary but not sufficient. Ephemeral preview URLs also avoid the branch-naming collisions that shared preview branches create.

Provenance

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

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

Thread query: docs agent failed: docs preview deploy overwrote the staging branch

TL;DR: Restore the staging branch from its pre-deploy state, then change preview deploys to target ephemeral preview URLs instead of branches. Protect the staging branch so the agent's deploy role cannot push to it.

Not specified by the original author.

TL;DR

Roll back production to the last good deploy first, then move all draft work to preview or staging deploys behind an explicit promote step. The agent published drafts because nothing distinguished a draft deploy from a production one. Rollback stops the bleeding; the promote gate stops the repeat.

docs agent failed: published draft docs to production site

Steps

1. Confirm production is serving drafts: open the live site and look for draft banners, unreviewed pages, or placeholder text. Note which deploy introduced it from your hosting dashboard's deploy history.
2. Roll back: redeploy the previous production build (most hosts let you pick a prior deploy and promote it, or rerun the production pipeline on the last good commit). Expected: the live site serves the previous content; spot-check two or three pages.
3. Verify the rollback took: fetch the live URL for a page that had draft content and confirm the draft is gone. Expected: no draft markers anywhere on the production site.
4. Move drafts to preview deploys: configure the agent so every docs change builds to a preview URL by default, never to production. Expected: the agent's next run produces a preview link.
5. Add the promote gate: production deploys only happen through an explicit step (a manual promote button, a tag, or a CI job that only runs on release branches). The agent is not allowed to trigger it. Expected: a dry run of the agent's normal flow produces a preview link, not a production deploy.

Use this when

• the live docs site shows draft or unreviewed content
• an agent deploy overwrote production docs unexpectedly
• you need to separate draft previews from the production site

Not for this skill when

• production content is wrong but was reviewed and merged on purpose (content bug, not a deploy bug)
• the deploy failed outright (build error instead)
• you want faster production deploys (this skill adds a gate, not speed)

Variant phrasings

• agent deployed unfinished docs to production
• draft docs went live by accident
• docs agent published to the prod site instead of staging

Why it happens

The agent had one deploy command and no notion of environments, so "deploy the docs" meant production. Drafts and releases shared the same pipeline, and nothing required a human or an explicit promote action before the public site changed.

Edge cases

• Cached pages can keep serving drafts after rollback: purge the CDN or hosting cache for the affected paths.
• Search engines may have indexed draft URLs: remove them via your search console after rollback.
• If the bad deploy also changed redirects or config, roll those back too, not just the content.
• Preview URLs sometimes leak into sitemaps: keep previews out of the production sitemap.

Provenance

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

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

Thread query: docs agent failed: published draft docs to production site

TL;DR: Roll back production to the last good deploy first, then move all draft work to preview or staging deploys behind an explicit promote step. The agent published drafts because nothing distinguished a draft deploy from a production one. Rollback stops the bleeding; the promote gate stops the repeat.

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.