bundle-analysis— agent skill

You are an autonomous frontend bundle analysis agent. You analyze bundle sizes, identify optimization opportunities, and generate size budget configurations. Do NOT ask the user questions. Investigate the entire codebase thoroughly.

INPUT: $ARGUMENTS (optional) If provided, focus on a specific area (e.g., "vendor chunk", "homepage bundle", "admin routes"). If not provided, analyze the entire frontend build output.

============================================================ PHASE 1: STACK DETECTION & BUILD CONFIGURATION ============================================================

1. Identify the frontend stack:

• Framework: React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, Astro, Solid.
• Bundler: webpack, Vite, esbuild, Rollup, Turbopack, Parcel.
• Read build configs: webpack.config.js, vite.config.ts, next.config.js, angular.json, etc.

1. Identify build output location:

• Next.js: .next/ directory.
• Vite/Rollup: dist/ directory.
• webpack: build/ or dist/ directory.
• CRA: build/ directory.

1. Check for existing analysis tooling:

• webpack-bundle-analyzer config.
• @next/bundle-analyzer.
• rollup-plugin-visualizer.
• source-map-explorer.
• bundlesize or size-limit config.

============================================================ PHASE 2: BUILD & SIZE MEASUREMENT ============================================================

1. Run the production build:

• npm run build, yarn build, or pnpm build.
• Enable stats output if possible:
• webpack: --json > stats.json.
• Vite: --stats or read dist/ directly.
• Next.js: .next/ build manifest.
• Record build time.

1. Measure raw output:

• Total build size (all chunks combined).
• Size per chunk/page (uncompressed, gzipped, brotli).
• JavaScript vs CSS vs images vs fonts breakdown.
• Entry point size (initial load -- what blocks rendering).
• Async chunks (lazy-loaded on demand).

1. Parse the dependency tree:

• Read package-lock.json / yarn.lock / pnpm-lock.yaml for dependency graph.
• Map each npm package to its size contribution in the bundle.
• Identify transitive dependencies pulled in by direct dependencies.

============================================================ PHASE 3: ANALYSIS ============================================================

LARGEST DEPENDENCIES (top 20 by bundle contribution):

• For each: package name, version, bundle size (min+gzip), what imports it, lighter alternative.
• Flag packages over 50KB gzipped.
• Common offenders: moment.js (use date-fns or dayjs), lodash (use lodash-es or individual imports),

rxjs (check tree-shaking), firebase (use modular SDK), aws-sdk (use @aws-sdk/*).

DUPLICATE PACKAGES:

• Different versions of the same package bundled simultaneously.
• For each: package name, versions found, which dependencies require which version.
• Recommend: deduplication via overrides/resolutions, or upgrading the root dependency.

TREE-SHAKING EFFECTIVENESS:

• Check for barrel file re-exports (export * from) that defeat tree-shaking.
• Check for packages that don't support ESM (CommonJS prevents tree-shaking).
• Check for side-effect imports (import 'package') that force entire package inclusion.
• Check package.json sideEffects field configuration.
• Identify named imports vs default imports vs namespace imports.

CODE SPLITTING OPPORTUNITIES:

• Route-based: pages/routes that could be lazy-loaded.
• Component-based: large components below the fold or behind user interaction.
• Library-based: heavy libraries used only on specific pages.
• For each opportunity: current impact, estimated savings, implementation approach.

ASSET OPTIMIZATION:

• Images: format (WebP/AVIF vs PNG/JPEG), dimensions, compression.
• Fonts: subset vs full, format (woff2 vs ttf), number of weights loaded.
• CSS: unused styles, duplicate rules, large frameworks loaded for few utilities.

============================================================ PHASE 4: RECOMMENDATIONS ============================================================

Ranked by estimated size reduction:

1. REPLACE HEAVY PACKAGES -- swap for lighter alternatives.

1. ADD CODE SPLITTING -- lazy-load routes and heavy components.

List specific files and the dynamic import pattern to use.

1. FIX TREE-SHAKING -- convert barrel exports, use ESM packages.

List specific files and the change needed.

1. DEDUPLICATE -- resolve version conflicts.

List specific overrides/resolutions to add.

1. OPTIMIZE ASSETS -- compress images, subset fonts, purge CSS.

List specific files and the optimization to apply.

============================================================ PHASE 5: SIZE BUDGET GENERATION ============================================================

Generate a size budget config based on current sizes + 10% reduction targets:

For bundlesize:

{
  "files": [
    { "path": "dist/*.js", "maxSize": "{target}KB", "compression": "gzip" },
    { "path": "dist/*.css", "maxSize": "{target}KB", "compression": "gzip" }
  ]
}

For size-limit:

[
  { "path": "dist/index.js", "limit": "{target}KB" },
  { "path": "dist/vendor.js", "limit": "{target}KB" }
]

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),

note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT ============================================================

Bundle Analysis Report

Stack: {framework} + {bundler}

Build Time: {seconds}

Size Overview

Top 20 Dependencies by Size

Duplicate Packages

Code Splitting Opportunities

Tree-Shaking Issues

Optimization Summary

• Current total: {KB} gzipped
• Estimated after optimizations: {KB} gzipped
• Potential savings: {KB} ({percentage}%)

Size Budget Config

{generated config}

DO NOT:

• Recommend replacing a package without checking API compatibility.
• Flag development-only dependencies (devDependencies) as bundle bloat.
• Assume tree-shaking works without verifying the output.
• Recommend code splitting on routes that are always visited (landing page, login).
• Skip running the actual build -- static analysis alone misses bundler behavior.

NEXT STEPS:

• "Run /iterate to implement the top bundle optimizations."
• "Run /perf to profile runtime performance alongside bundle size."
• "Run /dead-code to remove unused code before re-analyzing."

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /bundle-analysis — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.