Angular Optimizer

Audit an Angular codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Angular 22 made performance defaults stricter (zoneless since v21, OnPush by default) and those defaults expose code that mutates state without notifying Angular; changing change detection, hydration or rendering mode can silently change behavior, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the workspace root (package.json with @angular/core, angular.json). Record: Angular version (22.2 current), Node/TypeScript/RxJS versions, standalone vs NgModule, zoneless vs provideZoneChangeDetection, SSR/prerender, Material/CDK/Aria, test runner (Vitest default since v21), and whether it is a multi-project workspace.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, angular.json, tsconfig*.json, and .ts/.html sources for version skew, zone.js and OnPush migration gaps, legacy control flow/NgModules, eager routes, missing budgets, SSR/hydration gaps, subscriptions/timers/DOM leaks, XSS and strict-type issues, with file:line evidence. Use --json to post-process.
• Classify the pain: slow initial load (bundle/SSR), slow interactions (change detection/templates), memory growth (subscriptions/listeners), hydration/SEO, forms/a11y, test/build speed, or upgrade/migration. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (ng build, ng test, stats JSON, Angular DevTools, Chrome Angular track, Lighthouse).

2. Audit

The script finds cheap leads; you find the rest by reading. Read angular.json, tsconfig.json, src/main.ts, src/app/app.config.ts, the 3-5 hottest routes/components and the services they call. Load only what applies:

Measure, never guess. Build for production (ng build --configuration production) and serve that output, or run the SSR server, then measure. Dev mode, ng serve, and a single warm interaction are not evidence. Record route JS/CSS, initial bundle vs budgets, SSR TTFB/HTML, change-detection cycles in Angular DevTools, LCP/INP/CLS, memory/listener counts and hydration warnings.

Mark each finding Confirmed (build output, profiler, code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as ANGULAR_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- replace template method calls with computed/pure pipes, add track to @for (or trackBy to *ngFor), convert ChangeDetectionStrategy.Eager components that are signal-ready, add takeUntilDestroyed/toSignal, clear timers/listeners, add type="button", image alt/NgOptimizedImage, lazy-load heavy routes, add budgets. Low risk.
2. Structural -- convert manual subscriptions to signals/async pipe, split smart/presentational components, virtualize large tables (CDK), adopt loadComponent/@defer/injectAsync, add SSR/prerender and hydration where it fits, consolidate Material/Aria/CDK usage, split forms into signal/reactive patterns. Name each behavior change.
3. Heavy -- Angular major upgrade, zone.js → zoneless, NgModule → standalone, Karma/Jest → Vitest, Material M2 → M3, design-system extraction, rendering-mode change. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: ng build, ng test, ng lint, and the affected route/profile. A break must trace to one change. Do not mix a major-version migration with optimization edits. If a change alters public component inputs/outputs, routing/rendering mode, auth/data flow, or hydration boundaries, stop and ask.

6. Verify and wrap up

Re-measure the same routes and interactions: initial/route JS and CSS, build output vs budgets, SSR TTFB/HTML, Angular DevTools change-detection cycles, LCP/INP/CLS, memory/listener counts, hydration warnings, test time. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Angular 22 defaults are performance defaults. New apps are zoneless (v21+) and components are OnPush by default; ChangeDetectionStrategy.Default is now Eager. Treat explicit Eager as migration debt.
• Signals are the notification mechanism. In zoneless apps, a mutation that does not touch a signal, input, bound event or markForCheck() may not render. Convert state, not just templates.
• OnPush exposes hidden mutation. Mutating arrays/objects in place, storing subscription values on plain fields, or writing from outside Angular can freeze the view. Prefer immutable updates and signals.
• Templates are code. Method/getter calls, pipes that allocate, and heavy expressions run per check. Move work to computed, pure pipes or precomputed view models.
• Ship less by default. loadComponent, @defer, injectAsync, NgOptimizedImage, budgets and no zone.js beat micro-optimizations.
• Hydration is a contract. SSR markup must match client render; direct DOM access, random/time values and invalid HTML break it. Incremental hydration is on by default with provideClientHydration().
• Forms are a choice, not a rewrite. Signal Forms are stable in v22 for new forms; keep working reactive forms and migrate incrementally via the compat layer.
• Accessibility comes from CDK/Aria/Material. Use their dialogs, menus, focus traps and labels; do not rebuild behavior with clickable divs.
• Strict types and templates catch real bugs. strict, strictTemplates, typed forms and no any at boundaries are optimization work too.
• Migrations are one major at a time. ng update migrations preserve old behavior by design; remove the compatibility shims deliberately.
• Docs move. Check angular.dev for the installed major and read ng version, not memory.