Docs Fetch Fallbacks

/docs:fetch-fallbacks

A failed WebFetch is not a signal to retry the same URL. Re-issuing an identical request costs a round trip and returns the identical failure — the path is wrong, the resource is gated, or the host is slow, and none of those change between attempts. Read the failure signature, apply the fallback that matches it, and stop at two attempts.

Execution

Step 1: Read the failure signature

Note the status and the URL shape before acting — the same status means different things depending on where it lands:

Step 2: Apply the matching fallback

If two attempts both fail, surface the failure in the response — do not loop.

Step 3: Worked example — a GitHub blob URL

WebFetch returns 404 on:

https://github.com/laurigates/claude-plugins/blob/main/README.md?plain=1

Two things are wrong at once. Fix them cheapest-first rather than jumping to the authenticated call:

1. Strip the query → still 404, so the query was not the whole problem.
2. Swap the host → https://raw.githubusercontent.com/laurigates/claude-plugins/main/README.md — this is the fetch that succeeds for a public repo.
3. Still 404 or 403? The repo is private or rate-limited. Authenticate instead of guessing at more URL shapes:

gh api repos/laurigates/claude-plugins/contents/README.md \
  -H "Accept: application/vnd.github.raw+json"

That is attempt two. There is no attempt three.

For the full URL → gh command mapping (pulls, issues, commits, contents at a given ref), see git-plugin:gh-cli-agentic § GitHub URL Resolution — it owns that table. This skill covers only the recovery path after a fetch has failed.

Step 4: The SPA case — a 200 that carries no content

Every signature above is an error. This one is not: the request succeeds, the status is 200, and the HTML is a shell that a browser would fill in with JavaScript. Nothing in the result says "empty page" — instead the answer says it cannot see the content and asks you to paste it. That reads as a broken fetcher and invites a retry, which returns the identical shell.

The tell is the answer's shape, not a status code: it reports receiving only a heading or a title, and asks for the documentation to be provided. Two of those in a row on the same host means the host is client-rendered — stop fetching it.

The fallback is the docs' source, not the docs' URL. Most such sites render markdown that lives in a public repo, so fetch that file instead — and pin the ref to the version you actually depend on, which is strictly better than the "latest" the site would have shown you.

Worked example — verifying a Terraform resource's arguments and import ID format:

curl -fsSL "https://raw.githubusercontent.com/integrations/terraform-provider-github/v6.12.0/website/docs/r/team_members.html.markdown"

The tag matches the constraint in versions.tf, so the arguments read are the arguments that version accepts — a correctness gain over the registry page, not merely a workaround for it.

When no repo backs the site, context7 is the fallback source for a named library (Step 5), and it handles JS-rendered docs that a raw fetch cannot.

Step 5: Surface the failure

If the fallback also fails, say so in the response: name the URL, the status, and the fallback already tried. A third attempt with a cosmetically different URL is the failure mode this skill exists to prevent — the caller can supply a working URL far more cheaply than you can guess one.

When the content is documentation for a named library or framework, context7 and WebSearch are the fallback source, not another attempt at the same URL.