TL;DR: Diff the source commits behind the two versions, not the bundles. A worker bundle is a megabyte of minified code; the git diff of the source between the two deploys is usually a few dozen lines and tells you what actually changed.

```text
agent failed to diff worker versions: bundle too large for context window
```

## Steps

1. Find which source commit each deployed version was built from, using `wrangler versions list` and the version metadata.
   Expected: two commit SHAs, one per version, with no guessing.
2. Diff the source between them: `git diff [SHA_A] [SHA_B] -- src worker`.
   Expected: a readable diff of what actually changed, small enough to fit in context.
3. If only the bundles are available (no source access), split each bundle by module and hash every chunk; compare the two hash lists.
   Expected: a short list of changed modules instead of a megabyte diff.
4. Extract just the changed module bodies from both bundles and diff only those.
   Expected: a focused diff that fits in context.
5. Record the changed-module list in the triage note for the run.
   Expected: the next agent starts from the module list instead of re-diffing the whole bundle.

## Use this when

- An agent needs to know what changed between two worker deployments
- A bundle diff overflows the context window
- Triaging a regression that appeared between two versions

## Not for this skill when

- You need a byte-exact deploy artifact comparison (use checksums, not a diff)
- The two versions were built from identical source (the diff will be empty; check build config instead)
- Source history is available and small enough to just read directly

## Variant phrasings

- diff two cloudflare worker deployments too large
- worker bundle diff exceeds context limit
- what changed between worker versions
- compare wrangler deployments source diff

## Why it happens

Bundlers concatenate, minify, and rewrite every module into one artifact, so a one-line source change can shift thousands of bundle lines. Diffing bundles therefore costs context proportional to the whole app, while diffing the source costs context proportional to the actual change. Agents default to diffing what they can download (the bundle) instead of what is meaningful (the source).

## Edge cases

- If the deploy pipeline builds from a different branch than you assume, the SHAs from version metadata are the only trustworthy range.
- Dependency upgrades change the bundle without touching your source; `git diff` on the lockfile catches those.
- Wrangler version differences between builds can reformat the whole bundle; normalize by comparing source, not artifacts.
- For Workers Static Assets or Pages builds, diff the site source and the functions directory separately.

## Provenance

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