ln-832-bundle-optimizer Skill

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

ln-832-bundle-optimizer

Type: L3 Worker Category: 8XX Optimization

Reduces JavaScript or TypeScript bundle size using keep/discard verification. JS/TS projects only.

Overview

| Aspect | Details | |--------|---------| | Input | JS/TS project path plus optional optimization scope | | Output | Smaller bundle plus a machine-readable modernization summary | | Scope | JS/TS only |

Workflow

Phases: Pre-flight -> Baseline -> Analyze -> Optimize Loop -> Report

Phase 0: Pre-flight Checks

| Check | Required | Action if Missing | |-------|----------|-------------------| | package.json exists | Yes | Block optimization | | Build command available | Yes | Block optimization | | Output directory (dist/ or build/) detectable | Yes | Build once to establish baseline | | Workspace baseline safe | Yes | In managed runs coordinator already prepared it; in standalone runs protect rollback locally |

MANDATORY READ: Load references/ci_tool_detection.md for build detection. Tool policy: follow host AGENTS.md MCP preferences; load references/mcp_tool_preferences.md and references/mcp_integration_patterns.md only when host policy is absent or MCP behavior is unclear.

Use hex-graph first when hotspots or clone groups materially improve optimization targeting. Use hex-line first for local code and config reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in Read/Grep/Glob/Bash and state the fallback in the summary.

Runtime Coordination

Managed runs receive deterministic runId and exact summaryArtifactPath from ln-830. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

Phase 1: Establish Baseline

1. Run the detected build command.
2. Measure total size of the output directory.
3. Record baseline bytes and per-chunk sizes.

| Metric | How | |--------|-----| | Total size | Sum all bundle output files except source maps | | Per-chunk sizes | Measure individual JS and CSS files | | Source map handling | Exclude .map files |

Phase 2: Analyze Opportunities

| Check | Tool | What It Finds | |-------|------|---------------| | Unused dependencies | depcheck or equivalent | Packages not imported anywhere | | Bundle composition | Bundle analyzer | Large dependencies or duplicates | | Tree-shaking gaps | Manual scan | Namespace imports or heavy entrypoints | | Code splitting gaps | Route analysis | Lazy-load candidates |

Optimization categories:

| Category | Example | Typical Savings | |----------|---------|----------------| | Remove unused deps | dead dependencies | 10-50KB per package | | Named imports | lodash-es named imports | 50-200KB | | Lighter alternatives | replace heavy date or utility libs | 50-300KB | | Dynamic imports | lazy-load heavy components | lower initial bundle | | CSS optimization | remove unused CSS, minify | 10-100KB |

Phase 3: Optimize Loop (Keep/Discard)

Per-optimization cycle:

FOR each optimization:
  1. APPLY the change
  2. BUILD
     IF build fails -> DISCARD and revert
  3. MEASURE new bundle size
  4. KEEP only if the bundle is smaller than the current baseline
  5. LOG the result

Stop conditions:

| Condition | Action | |-----------|--------| | All optimizations processed | Stop and report | | 3 consecutive discards | Stop for plateau | | Build infrastructure breaks | Revert to last keep and stop | | Bundle already below target | Stop and report |

Optimization order:

remove unused dependencies
improve tree-shaking and imports
replace heavy libraries
introduce code splitting
optimize CSS

Phase 4: Report Results

| Field | Description | |-------|-------------| | project | Project path | | baseline_bytes | Original bundle size | | final_bytes | Final bundle size | | reduction_bytes | Bytes saved | | reduction_percent | Percentage reduction | | optimizations_applied | Count of kept optimizations | | optimizations_discarded | Count plus reasons | | deps_removed[] | Dependencies removed | | details[] | Per-optimization savings | | artifact_path | Durable worker report path, if written |

Configuration

Options:
  build_command: ""             # Auto-detect
  output_dir: ""                # Auto-detect
  run_depcheck: true
  run_bundle_analyzer: false
  remove_unused_deps: true
  fix_tree_shaking: true
  replace_heavy_libraries: true
  enable_code_splitting: true

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Build fails after optimization | Invalid code or config change | Revert that optimization | | No size reduction | Optimization ineffective | Discard it | | Analyzer unavailable | Tooling missing | Continue with manual inspection |

References

optimization_categories.md
references/ci_tool_detection.md

Runtime Summary Artifact

MANDATORY READ: Load references/coordinator_summary_contract.md

Emit a modernization-worker summary envelope.

Managed mode:

ln-830 passes deterministic runId and exact summaryArtifactPath
write the summary to the provided summaryArtifactPath

Standalone mode:

omit runId and summaryArtifactPath
write .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-832--{identifier}.json

Monitor (2.1.98+): For build commands in keep/discard loop expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

[ ] Baseline bundle size established from real build output
[ ] Optimization opportunities analyzed from bundle composition and project usage
[ ] Each optimization evaluated with keep/discard verification
[ ] Only size-reducing optimizations kept
[ ] Final report captures bundle delta, discarded attempts, and removed dependencies
[ ] modernization-worker summary artifact written to the managed or standalone path

Version: 1.0.0 Last Updated: 2026-03-08

Agent Skills: ln-832-bundle-optimizer

Install this agent skill to your local

Skill Files