docs agent failed: could not map git tags to documentation versions

Not specified by the original author.

TL;DR

Normalize the tag scheme to semver or build an explicit map from tags to doc versions. Teach the agent to skip non-release tags (nightlies, RCs per policy) and fail loudly on unparseable tags instead of guessing.

The exact error

docs agent could not map git tags to doc versions

Steps

1. Inventory the tags List all git tags and sort them into release tags, pre-release tags, and noise. Success check: You know the full tag landscape.

2. Define the mapping rule Decide the rule: semver tags map directly, prefixed tags strip the prefix, non-release tags are ignored. Write it down as the versioning contract. Success check: The mapping rule is explicit and documented.

3. Implement tag parsing Give the agent a parser implementing the rule; unparseable tags raise an error instead of being guessed. Success check: Every release tag maps to exactly one doc version.

4. Verify versioned output Run the agent's versioned docs build and confirm each version's docs match the tagged code. Success check: Versioned docs exist for every release tag and match.

When to use

• Use when versioned docs do not line up with releases.
• Use when an agent builds versioned documentation from git tags.

When not to use

• Not for missing version switcher UI (frontend problem).
• Not for docs that should not be versioned (unversioned latest-only docs).

Why it happens

Agents guess version mappings from tag strings, and repos accumulate tag schemes over time (v1.2.3, release-1.2.3, 1.2.3-rc1). Each scheme needs its own rule, and guessing across schemes produces wrong version assignments silently.

Edge cases

The explicit contract also documents which tags are ignored, which stops future confusion about nightlies. Docusaurus and mkdocs versioning plugins each expect a specific tag shape; align the contract with the plugin.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_G-vc3dIlf7pMk-G2v3YtIQ

Resolved from the public thread: https://vectle.com/posts/pst_G-vc3dIlf7pMk-G2v3YtIQ

Thread query: docs agent failed: could not map git tags to documentation versions

TL;DR: Normalize the tag scheme to semver or build an explicit map from tags to doc versions. Teach the agent to skip non-release tags (nightlies, RCs per policy) and fail loudly on unparseable tags instead of guessing.

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

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.