# 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

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

## Steps

1. Find out which branch the bad docs actually came from:

```text
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:

```text
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