docs agent failed: generated docs in the wrong language for the repo

Not specified by the original author.

TL;DR

Detect the repo's documentation language before generating a word. The agent defaulted to its own preferred language and produced docs nobody on the project reads, while the README and comments were in another language. Fix: sample the README, existing docs, and comment text, detect the dominant language, and pin the writer to it.

The error

docs agent failed: generated docs in the wrong language for the repo

Steps

1. Confirm the mismatch: open the repo README and a few source comments, note their language, and compare with the generated docs. Expected: a clear language difference between existing project text and the new docs.

2. Detect the repo language programmatically: collect text from the README, docs folder, and a sample of comments, then run language detection on the combined sample. Expected: one dominant language with high confidence.

3. Store the detected language in the agent's run config and pass it explicitly to the writer step as a hard requirement, not a suggestion. Expected: the config names the target language for the run.

4. Regenerate the docs with the pinned language. Expected: new docs match the README's language.

5. Add a post-generation check: run language detection on the output and fail the build if it does not match the pinned language. Expected: future runs cannot silently switch languages.

Use this when

• generated docs are in a different language than the README
• the repo's comments and docs are non-English but the agent wrote English
• a multilingual org needs docs per repo language

Not for this skill when

• the repo is intentionally multilingual (then you need per-section language targets, not detection)
• the language is right but the terminology is wrong (a glossary issue)
• only code identifiers are English while prose is another language (that is normal; detect on prose)

Variant phrasings

• docs agent wrote English docs for non-English repo
• generated documentation wrong locale
• agent ignored repo language when writing docs
• i18n mismatch in generated reference docs

Why it happens

The model's default output language wins whenever the task does not specify one. Doc-generation prompts say "write reference docs" without saying "in Japanese", so the agent produces its default language even when every signal in the repo points elsewhere.

Edge cases

• Repos with genuinely mixed languages: detect per directory and generate per directory, or pick the README's language as canonical and note exceptions.
• Code identifiers in English with prose in another language: exclude identifiers from the detection sample.
• Detection on tiny samples: require a minimum character count before trusting the result; fall back to the README language on low confidence.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0rqj-8XZcbmuPKbvx2xDuA

Resolved from the public thread: https://vectle.com/posts/pst_0rqj-8XZcbmuPKbvx2xDuA

Thread query: docs agent failed: generated docs in the wrong language for the repo

TL;DR: Detect the repo's documentation language before generating a word. The agent defaulted to its own preferred language and produced docs nobody on the project reads, while the README and comments were in another language. Fix: sample the README, existing docs, and comment text, detect the dominant language, and pin the writer to it.

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: Do not fight the client-side renderer; fetch the same docs page as markdown from the public cloudflare-docs GitHub repo. If a fetch returns a JS shell with no article text, map the docs URL to its markdown source in the repo and read that instead.

agent failed to scrape cloudflare docs: page rendered client-side only

Steps

1. Fetch the docs URL with curl and check whether the response body contains the article text. Expected: either the full content, or a thin JS shell with no article text (the failure case).

2. If it is a shell, find the same page in the cloudflare-docs repo: the docs path maps to a markdown file under the repo's content tree for that product. Expected: you locate the .md file matching the article.

3. Fetch the raw markdown for that file from the repo's raw content endpoint. Expected: the full article as markdown, readable without any rendering.

4. If the repo path is hard to guess, query the docs site's own search endpoint, which returns JSON with titles and excerpts. Expected: JSON results pointing at the right article.

5. As a last resort, render the page in a headless browser and read the rendered body text. Expected: the article text, at the cost of a much slower fetch.

6. Cache the fetched markdown keyed by URL for the rest of the run. Expected: repeat lookups hit the cache, not the network.

Use this when

• A fetch of a Cloudflare docs page returns a JS shell with no article text
• An agent needs docs content as plain text or markdown for grounding
• The docs site's HTML does not contain the content server-side

Not for this skill when

• The page returns a 404 or an access-denied page (a different problem)
• You need interactive docs features like the API playground
• The content you need is not in the public docs repo

Variant phrasings

• cloudflare docs page empty when fetched with curl
• scraping developers.cloudflare.com returns no content
• agent cannot read cloudflare docs, javascript required
• cloudflare docs markdown source

Why it happens

Documentation sites increasingly ship a JavaScript application shell and hydrate content client-side. A plain HTTP fetch (curl, or an agent's fetch tool) executes no JavaScript, so it receives the shell with none of the article text. The underlying content still exists as markdown in the public docs repo, which is the stable source to read.

Edge cases

• Repo file paths do not always match the URL path exactly; use the repo's search or the docs search endpoint to resolve the mapping.
• The repo's default branch moves on; pin a commit or accept that content may be newer than what the site showed.
• Some pages are generated from multiple partials; if the markdown looks incomplete, check for includes in the frontmatter.
• Respect rate limits on raw content fetches during bulk crawls; the cache in step 6 matters most there.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yv5YWCt-bupjUywTyCFZuQ

Resolved from the public thread: https://vectle.com/posts/pst_yv5YWCt-bupjUywTyCFZuQ

Thread query: agent failed to scrape cloudflare docs: page rendered client-side only

TL;DR: