docs agent failed: api reference built from the wrong git tag

Not specified by the original author.

TL;DR

Check out the intended tag before generating and verify with git describe. Agents that generate from whatever is checked out document whatever happens to be there.

Error

(api reference documents v2.0 while the release is v2.1; no error text)

Steps

1. Check what is actually checked out in the agent workspace: git describe --tags and git status. Expected: the real checked-out ref, which often is not what was assumed.
2. Check out the intended tag explicitly: git checkout v2.1.0 (or the release branch), and make the checkout a named, logged step in the job. Expected: the workspace is on the right ref.
3. Verify a version-identifying symbol (version constant, changelog head) matches the intended release before generating. Expected: independent confirmation of the right version.
4. Re-run generation. Expected: the reference matches the intended tag.

When to use

• The reference documents the wrong version
• The agent reuses a workspace across releases
• Releases are cut from tags the agent never checks out

When not to use

• The workspace is on the right tag but docs still lag (a generation or cache problem)
• The wrong content comes from a submodule (a submodule sync problem)
• You document a branch, not a tag (check out the branch instead)

Tool compatibility

Git with any generator. The checkout-verify pattern is tool-independent.

Variant phrasings

agent builds from main instead of the release tag

Pin the ref in the job definition; do not rely on the workspace default.

tag exists locally but not in the agent's clone

Fetch tags explicitly: git fetch --tags before checkout.

Why it happens

Agent workspaces persist across runs, and nothing forces a checkout to the release ref. Generation runs against the stale checkout and produces confidently wrong versioned docs.

Provenance

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

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

Thread query: docs agent failed: api reference built from the wrong git tag

TL;DR: Check out the intended tag before generating and verify with git describe. Agents that generate from whatever is checked out document whatever happens to be there.

Not specified by the original author.

TL;DR

Make the agent update the submodule before generating: git submodule update --init --recursive. Generating from a stale checkout silently documents old code.

Error

(api reference documents v1.4 symbols; the submodule already contains v1.5; no error text)

Steps

1. Check the submodule state in the agent's workspace: git submodule status. Expected: you see whether the checked-out commit matches the expected one.
2. Add an explicit sync step at the start of the agent's docs job: git submodule update --init --recursive. Expected: the submodule checks out the commit the superproject pins.
3. Verify the sync took effect by comparing a known-new symbol: grep the submodule source for it before generating. Expected: the new symbol is present in the checked-out files.
4. Re-run generation. Expected: the API reference reflects the current submodule commit.

When to use

• Generated docs describe older code than the submodule contains
• The agent clones fresh each run without initializing submodules
• API reference is missing recently added modules

When not to use

• The reference is built from the wrong git tag (a tag problem, not a submodule problem)
• The submodule is current but generation still lags (check the generator's own caching)
• There is no submodule involved at all

Tool compatibility

Git submodules with any docs generator (Sphinx, TypeDoc, JSDoc). The sync command is the same everywhere.

Variant phrasings

agent updated the submodule but generated docs still stale

The generator ran before the sync in the job order. Sequence sync first, generate second.

submodule points at the wrong commit after sync

The superproject pins the commit. Update the pin with git submodule update --remote only if tracking a branch intentionally.

Why it happens

Fresh clones do not check out submodule contents by default, and agents rarely add the init step. The generator then documents whatever stale files happen to be there, or nothing at all.

Provenance

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

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

Thread query: docs agent failed to sync docs submodule before generating api reference

TL;DR: Make the agent update the submodule before generating: git submodule update --init --recursive. Generating from a stale checkout silently documents old code.

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.