# docs agent's browser automation failed on readthedocs deploy preview page

## TL;DR
Skip the browser and verify the preview through the build status plus a direct fetch of the built HTML. The preview page is script-heavy and often still building when the agent loads it, so automation sees a spinner or stale content and fails. Poll for build success first, then fetch the page directly.

## The error

```text
docs agent's browser automation failed on readthedocs deploy preview page
```

## Steps

1. Check the build state before loading anything. Open the project's Read the Docs dashboard or query the builds API for the version being previewed.

Expected: you see whether the preview build is still running, failed, or finished successfully.

2. If the build is still running, wait for success. Poll every 30 seconds with a cap, and do not let the automation touch the preview URL until the build reports success.

Expected: no more automation racing a half-built page.

3. Fetch the preview URL directly with a plain HTTP request instead of a full browser. Copy the preview URL from the build record rather than guessing its shape.

Expected: a 200 response with the built HTML, confirming the preview exists and renders.

4. Only use browser automation for checks that truly need scripting, and wait on the content selector explicitly instead of using fixed sleeps.

Expected: the check passes deterministically instead of flaking on load timing.

## Use this when

- agent checks against Read the Docs preview pages flake or time out
- the preview shows a spinner or outdated content during automation
- the same check passes when a human retries it a minute later

## Not for this skill when

- the Read the Docs build itself is failing (fix the build)
- the preview URL 404s after a successful build (check the version slug)
- the automation never worked, even on a finished build (check the automation setup)

## Variant phrasings

### readthedocs preview not loading in automation
Poll the build status first; the page is not ready until the build is.

### browser check fails on RTD deploy preview
Replace the browser with a direct fetch unless the check needs scripting.

### preview page shows old content in CI
The agent loaded it mid-build. Gate the check on build success.

## Why it happens
The preview page renders before the build artifacts exist and updates itself with scripting as the build progresses. Automation that does not wait on build state races the deploy: it screenshots a spinner, reads stale HTML, or times out, then reports a failure that is really just bad timing.

## Edge cases

- Pull request previews need the PR-build toggle enabled in the Read the Docs settings, or there is no preview to check at all.
- The preview URL pattern differs between PR builds and version builds. Copy it from the build record instead of constructing it.
- Auth-walled docs will show the automation a login page. The check needs the sharing access configured or it will always fail.
- A build that reports success but serves stale content usually means a CDN cache; check cache headers before blaming the automation.

## Provenance

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