Image debt scan

Locate the images worth converting to hand-authored SVG. This is the reconnaissance step before arbitrum-brand-svg-diagrams.

When to use

• "Which images should we convert next?" / "find our heaviest diagrams"
• Planning a batch cleanup of public/img/
• Before dispatching diagram-converter subagents: this produces their work list

When NOT to use

• Photos/screenshots: they legitimately stay raster (only diagrams convert well)
• A single known file: just use arbitrum-brand-svg-diagrams directly

The blind spot this skill exists to close

The biggest image debt in this repo is not the PNGs: it's .svg files that are actually a base64-encoded raster wrapped in draw.io/editor XML. They carry a .svg extension (so a naïve size scan of *.png/*.jpg misses them entirely) yet weigh 1 to 6 MB each and blur when zoomed. A whole-repo scan this session found ~15 of them at ~6 MB apiece (e.g. haw-token-gateway.svg, haw-batching.svg, apps-pull-oracle.svg, arb-chain-aep-scenario-*.svg). The scanner detects them by grepping each .svg for data:image/…;base64 (and mxfile for draw.io).

Run the scan (driver)

scan.sh reports raster-in-SVG first (top debt), then oversized rasters, each with the MDX pages that reference it (or unreferenced = deletion candidate). Sizes are largest-first.

# whole repo
.agents/skills/image-debt-scan/scan.sh

# scope the reference search to one section (only reports images that section uses)
.agents/skills/image-debt-scan/scan.sh content/docs/how-arbitrum-works

# raise the raster threshold (default 300 KB; raster-in-SVG is always reported)
THRESHOLD_KB=500 .agents/skills/image-debt-scan/scan.sh

Sample output (from the Docusaurus tree; paths and sizes differ here):

== Raster-in-SVG (draw.io / embedded-raster wearing a .svg extension: top debt) ==
   6584 KB  public/img/haw-token-gateway.svg  [embedded-raster]
           (unreferenced: candidate for deletion)
   6087 KB  public/img/apps-pull-oracle.svg  [embedded-raster]
           content/docs/build-decentralized-apps/oracles/01-overview.mdx
   1863 KB  public/img/arb-chain-aep-scenario-2.svg  [draw.io PNG-in-SVG]
           content/docs/launch-arbitrum-chain/.../02-set-up-aep-fee-router.mdx
== Raster images over 300 KB (convert diagrams; keep photos/screenshots) ==
   7863 KB  public/img/bold-before-vs-after-with-bold.png
           content/docs/how-arbitrum-works/bold/gentle-introduction.mdx

Triage the output

Rank into tiers, biggest + most-referenced first:

1. Raster-in-SVG, referenced → convert (highest value). Filename ends in .svg, so arbitrum-brand-svg-diagrams can replace it in place with no MDX edit and no check-links risk. This is the sweet spot.
2. Raster-in-SVG, unreferenced → delete. Dead weight; confirm with the user, then trash (never rm).
3. Heavy PNG/JPG that is a concept diagram → convert (boxes, flows, flat fills). Converting changes the extension, so the MDX src= must be updated.
4. Heavy PNG/JPG that is a photo/screenshot/pie-chart → keep, optionally recompress. Gradients and fine detail don't vectorize well.

Report a ranked table: size · path · referencing pages · verdict. Do not convert here: that's the SVG skill's job. Hand the "convert" list to a diagram-converter subagent per file (parallel) or arbitrum-brand-svg-diagrams for one.

Gotchas

• .svg extension guarantees nothing. Always grep for base64/mxfile: head -c 2000 can miss a base64 blob that starts later in the file (some Serif/Affinity exports reference embedded images via <use xlink:href> well past the header), so scan.sh greps the whole file.
• Genuine large vector exists (e.g. an 80 KB Graphviz UML with no base64), and it is not flagged, correctly. Size alone isn't the signal; base64 is.
• rg may be rewritten to grep by a shell hook here; scan.sh uses grep -r directly to avoid that.

See also

• arbitrum-brand-svg-diagrams (under .agents/skills/ and .claude/skills/) does the actual conversion.
• Subagent diagram-converter (.codex/agents/diagram-converter.toml) parallelizes conversion across the list.