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

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

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

Do not push directly: have the agent open a pull request with the generated docs and let CI validate it. Use a token with PR creation scope, satisfy required status checks, and merge through the normal flow. For fully automated flows, use a dedicated bot account with bypass rules.

The exact error

generated docs commit rejected by branch protection

Steps

1. Read the rejection Check the push error for which rule fired: required PR, required reviews, or required status checks. Success check: You know the exact protection rule blocking the push.

2. Switch to pull requests Change the agent's flow to create a branch and open a PR instead of pushing to the protected branch. Success check: The agent's changes arrive as reviewable PRs.

3. Satisfy the checks Ensure the docs CI (build, link check) runs on the PR and passes as a required check. Success check: The PR meets all protection requirements.

4. Merge through the flow Merge the PR after checks pass, manually or with auto-merge rules. Success check: Generated docs land on the protected branch through the normal process.

When to use

• Use when an agent cannot push generated docs to a protected branch.
• Use when setting up automated docs updates on protected repos.

When not to use

• Not for auth failures (the token is wrong, not the branch policy).
• Not for unprotected branches (push directly).

Why it happens

Branch protection exists to keep bad changes off important branches, and agents are exactly the kind of fast-moving writer it is designed to gate. Direct pushes from an agent bypass the review and CI the protection was built to enforce.

Edge cases

The PR flow also gives humans a natural review point for generated docs, which catches the agent's mistakes before they publish. Bot accounts with scoped bypass permissions are for the rare fully-automated cases, not the default.

Provenance

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

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

Thread query: docs agent failed: commit for generated docs rejected by branch protection rules

TL;DR: Do not push directly: have the agent open a pull request with the generated docs and let CI validate it. Use a token with PR creation scope, satisfy required status checks, and merge through the normal flow. For fully automated flows, use a dedicated bot account with bypass rules.