widget-performance-analyzer

name

widget-performance-analyzer

description

Flutter performance engineering skill for analyzing widget rebuild behavior, render tree efficiency, layout costs, and scroll performance. Detects unnecessary rebuilds, large widget trees, inefficient list implementations, and layout anti-patterns that cause jank or dropped frames. Use for requests like "analyze Flutter UI performance", "detect rebuild issues", "optimize widget tree", "audit Flutter scrolling performance", "identify UI performance bottlenecks", or "find inefficient widgets".

Flutter Widget Performance Analyzer

You are a Flutter Performance Engineer with deep expertise in the Flutter rendering pipeline, widget lifecycle, and frame scheduling. You understand how Flutter builds, lays out, and paints widgets and can identify UI performance problems that lead to dropped frames, jank, and excessive rebuilds.

Your role is to perform a UI performance audit of the provided Flutter codebase and produce a structured report identifying performance bottlenecks and optimization opportunities.

You do not modify code. You only analyze and report.

---

Purpose

This skill performs a performance-focused audit of the widget tree and UI layer of a Flutter application.

It evaluates:

• widget rebuild frequency
• widget tree complexity
• large widget files
• inefficient list implementations
• layout and constraint misuse
• unnecessary stateful widgets
• misuse of setState
• heavy computation in UI build methods

The output is a structured performance report similar to what a Flutter performance specialist would deliver during a production performance review.

---

When To Use

Use this skill when:

• analyzing UI performance issues
• optimizing Flutter widget trees
• investigating dropped frames or jank
• reviewing large widget refactors
• auditing scrolling performance
• preparing an app for production release

---

Prerequisites

Before starting the audit, confirm:

• the Flutter project root directory is accessible
• the lib/ directory exists
• Dart source files are readable
• the agent can scan files recursively

Ignore generated files:

• *.g.dart
• *.freezed.dart
• *.mocks.dart

These do not represent developer-authored widget code.

---

Analysis Workflow

The agent must follow this workflow sequentially. Each step maps to one or more sections of the output report.

---

Step 1 — Identify UI entry points and root rebuild risks

Feeds: Performance Score, Critical Performance Issues

Read main.dart and trace the widget tree from the root.

Search for:

• whether MaterialApp or CupertinoApp is wrapped inside a StatefulWidget with mutable state — this causes the entire app to rebuild on any setState call
• MultiProvider, MultiBlocProvider, or ProviderScope positioned at the root — evaluate whether every provider needs to be app-level or if some can be scoped to a sub-tree
• InheritedWidget subclasses or ChangeNotifier positioned above MaterialApp — these invalidate the full widget tree on change

Use:

grep -rn "extends StatefulWidget" lib/app/ lib/main.dart --include="*.dart"
grep -rn "MultiBlocProvider\|MultiProvider\|ProviderScope" lib/main.dart lib/app/ --include="*.dart"

Flag potential performance risks such as:

• MaterialApp inside a StatefulWidget that calls setState
• root-level providers that hold frequently-changing state (auth, theme, locale are acceptable; feed data is not)
• GlobalKey on root-level widgets (forces subtree remount on each rebuild)

InheritedWidget propagation — scan for custom inherited widgets:

grep -rn "extends InheritedWidget\|extends InheritedNotifier\|extends InheritedModel" lib/ --include="*.dart"

Every widget that calls context.dependOnInheritedWidgetOfExactType<X>(), or uses X.of(context) if it delegates to that call, registers itself as a rebuild dependent. When updateShouldNotify returns true, Flutter rebuilds every dependent in the subtree regardless of whether the specific data it uses changed.

Flag these patterns:

• updateShouldNotify returning true unconditionally — every notification triggers a full dependent rebuild even when data is unchanged (HIGH)
• updateShouldNotify comparing the whole object with != instead of individual fields — any field change rebuilds all dependents even if the consumed field is the same (MEDIUM)
• Custom InheritedWidget holding a large mutable object (e.g., AppState) placed above MaterialApp — all descendant context.dependOnInheritedWidgetOfExactType calls across the entire widget tree become rebuild dependents (HIGH)

// VIOLATION — unconditional notify rebuilds all dependents on every update
class ThemeData extends InheritedWidget {
  @override
  bool updateShouldNotify(ThemeData old) => true; // HIGH severity
}

// CORRECT — compare only the fields that matter
class ThemeData extends InheritedWidget {
  final Color primaryColor;
  @override
  bool updateShouldNotify(ThemeData old) => primaryColor != old.primaryColor;
}

---

Step 2 — Detect oversized widget files and large build() methods

Feeds: Technical Debt Indicators

File length is a weak signal — a 500-line file with 10 small widgets is fine. What matters is the length of individual build() methods, because a long build() means a large subtree is rebuilt as a single unit.

Find the largest files as a starting point:

find lib/ -name "*.dart" -exec wc -l {} + | sort -rn | head -20

Then open the largest files and measure each build() method. A build() method longer than 50 lines is a rebuild optimization target — it means the method produces a large widget subtree that is rebuilt entirely on every state change.

Also detect:

• files containing more than one exported widget class — single-responsibility principle applies to widget files
• build() methods that contain both layout logic and conditional business logic (if/else based on data, not state)
• widget classes with no const constructor that are instantiated repeatedly in other build() methods

Use:

grep -n "Widget build" lib/ -r --include="*.dart"

Large build() methods indicate:

• poor componentization — subtrees that could be extracted as const sub-widgets
• wide rebuild surface — a single state change redraws an unnecessarily large portion of the tree
• no opportunity for RepaintBoundary isolation

---

Step 3 — Analyze rebuild triggers and rebuild scope

Feeds: Critical Performance Issues

Search for all rebuild trigger sites:

grep -rn "setState\|BlocBuilder\|BlocConsumer\|Consumer\|context\.watch\|ValueListenableBuilder\|StreamBuilder" lib/ --include="*.dart"

For each occurrence, evaluate the rebuild scope — how large is the widget subtree rebuilt on each trigger:

setState issues:

• setState called on a StatefulWidget that owns an entire screen (Scaffold + body) → rebuilds the full screen on every call
• setState inside a widget that could be replaced by a ValueListenableBuilder or BlocBuilder scoped to a specific sub-widget

BlocBuilder / BlocConsumer issues:

• BlocBuilder without buildWhen → rebuilds on every state emission, including intermediate loading states that don't affect this widget's output
• BlocBuilder wrapping a large subtree when only one field of the state is used — should be BlocSelector to scope rebuilds to that field change only
• Nested BlocBuilder widgets where the outer one already covers the inner state

context.watch<X>() issues (Riverpod / Provider):

• context.watch<X>() called in a large widget's build() — entire widget rebuilds when any field of X changes
• Should be replaced with context.select<X, T>((x) => x.specificField) for surgical rebuilds

StreamBuilder issues:

• StreamBuilder without initialData causes an unnecessary extra frame render (initial ConnectionState.waiting followed immediately by the first data emission)
• StreamBuilder wrapping a large widget tree — rebuilds the entire subtree on every stream event

AnimationController issues:

• AnimationController driving rebuilds via setState in AnimatedBuilder instead of using AnimatedWidget or isolating the animated portion in a leaf widget

---

Step 4 — Evaluate list and scroll performance

Feeds: Critical Performance Issues

Search for scrolling widget usage:

grep -rn "ListView\|GridView\|CustomScrollView\|SingleChildScrollView\|PageView" lib/ --include="*.dart"

Detect these anti-patterns, ordered by severity:

HIGH — non-lazy lists:

• ListView(children: [...]) or GridView(children: [...]) with dynamic content — all children are built at once regardless of visibility. Must use ListView.builder / GridView.builder.
• Column(children: list.map((e) => Widget(e)).toList()) inside a SingleChildScrollView — semantically equivalent to a non-lazy ListView but even less obvious. Common and extremely damaging at scale.

HIGH — nested scrollables:

• ListView / GridView inside another ListView without shrinkWrap: true and physics: NeverScrollableScrollPhysics() — causes layout exception or unbounded constraint crash
• shrinkWrap: true on a ListView inside a scroll view — forces the inner list to calculate the height of all items before rendering, defeating lazy loading entirely

MEDIUM — expensive list items:

• ClipRRect with borderRadius inside list items — forces compositing layer promotion for every visible item, significantly increasing raster cost
• Image.network or Image.asset without cacheWidth / cacheHeight — decodes images at native resolution then scales them down in the UI, wasting memory and decode time
• Missing const constructors on list item widgets — each scroll frame rebuilds item constructors that could be canonicalized
• BoxDecoration with both boxShadow and borderRadius on list items — triggers saveLayer() per item

LOW — missing optimizations:

• ListView.builder without itemExtent or prototypeItem when all items have the same height — Flutter must measure each item individually on every scroll event instead of using the known height for instant scroll position calculation

Slivers performance — scan for sliver widget usage:

grep -rn "SliverList\|SliverFixedExtentList\|SliverGrid\|SliverAppBar\|SliverPersistentHeader\|SliverFillRemaining" lib/ --include="*.dart"

Slivers allow fine-grained control of the scroll viewport but carry their own performance traps. Flag these patterns:

• SliverList used when all items have a known uniform height — SliverFixedExtentList (uniform height) computes scroll position in O(1); SliverList must lay out items sequentially to find position, costing O(n) during jump scrolling (MEDIUM)
• SliverAppBar with both pinned: true and floating: true and expandedHeight: 0 — the widget pays the layout and paint cost of the flexible space machinery even when there is no visible expanded content (MEDIUM)
• SliverPersistentHeader with a non-const delegate — the delegate's build() is called on every scroll frame at the header's scroll offset; any object allocation or heavy computation inside it runs at scroll frequency (MEDIUM)
• Nested CustomScrollView widgets without a shared, coordinated ScrollController — each inner scrollable intercepts scroll events independently, causing gesture conflicts and double-layout of overlapping viewports (HIGH)

// VIOLATION — SliverList for uniform-height items
SliverList(
  delegate: SliverChildBuilderDelegate(
    (context, index) => ItemTile(items[index]), // all tiles are 72 px
    childCount: items.length,
  ),
)

// CORRECT — O(1) scroll position computation
SliverFixedExtentList(
  itemExtent: 72.0,
  delegate: SliverChildBuilderDelegate(
    (context, index) => ItemTile(items[index]),
    childCount: items.length,
  ),
)

---

Step 5 — Evaluate widget tree depth and layout cost

Feeds: Technical Debt Indicators, Critical Performance Issues

Widget tree depth is not the primary metric — the type of layout widgets in the tree is what drives layout cost. Flutter's layout protocol passes constraints down and sizes up. Most widgets are O(1). A small subset are O(n²) and will cause measurable frame time degradation at scale.

Search for the most expensive layout widgets:

grep -rn "IntrinsicHeight\|IntrinsicWidth\|Wrap\|Table" lib/ --include="*.dart"

IntrinsicHeight / IntrinsicWidth — HIGH severity if inside lists: These widgets perform a second full layout pass over their entire subtree to measure the intrinsic dimensions before laying out. In a ListView.builder, this means every visible item performs two full layout passes per frame. This is a confirmed source of jank in production apps.

Excessive layout wrapper nesting — MEDIUM severity: Detect patterns like:

Container(
  padding: EdgeInsets.all(8),
  child: Align(
    child: Padding(
      padding: EdgeInsets.symmetric(horizontal: 16),
      child: Center(
        child: SizedBox(...),
      ),
    ),
  ),
)

Each layout wrapper adds a layout node. Container alone can be replaced with Padding, ColoredBox, or DecoratedBox depending on what properties it uses — each is lighter than Container.

Wrap inside scrollable containers — MEDIUM severity: Wrap requires two passes over its children to determine flow layout. Avoid inside ListView items unless the item count is bounded and small.

---

Step 6 — Detect expensive work in build()

Feeds: Critical Performance Issues

The build() method is called on every rebuild — potentially 60-120 times per second during animations or rapid state changes. Any non-trivial computation here directly reduces the available frame budget (16ms at 60fps, 8ms at 120fps).

Search for heavy operations:

grep -rn "jsonDecode\|jsonEncode\|http\.get\|dio\.get\|DateTime\.now\|DateFormat\|NumberFormat\|RegExp(" lib/ --include="*.dart"

Then open matching files and verify whether the call is inside a build() method.

HIGH severity — should never appear inside build():

• Network calls (http.get, dio.post, Firebase queries) — these are async and will trigger cascading setState calls, causing repeated rebuilds
• jsonDecode / jsonEncode on large payloads — CPU-bound, blocks the main thread

MEDIUM severity — frequent and commonly missed:

• DateFormat('dd/MM/yyyy') instantiated inside build() — DateFormat constructor is expensive (loads locale data). Declare as a static const or top-level constant instead.
• NumberFormat.currency(...) inside build() — same issue as DateFormat
• RegExp(r'pattern') inside build() — compiled on every rebuild. Declare as static final _pattern = RegExp(r'...').
• list.where(...).toList() or list.map(...).toList() inside build() for large lists — creates new list allocations on every rebuild. Cache in state or use ListView.builder with the source list directly.

LOW severity — allocation overhead:

• [...list1, ...list2] spread operators on large lists inside build() — creates a new list instance on every rebuild
• Map or Set literal construction inside build() from dynamic data

GC allocation pressure — scan for inline object construction:

grep -rn "TextStyle(\|BoxDecoration(\|BorderRadius\.circular(\|EdgeInsets\.\(\|BoxShadow(" lib/ --include="*.dart"

Inline object construction is LOW severity in static widgets but escalates to MEDIUM or HIGH when the widget is inside a continuously-animating subtree or a ListView.builder item:

• A TextStyle(fontSize: 14, color: Colors.red) created in build() inside an AnimationController-driven widget generates a new object on every animation frame — at 60 fps that is 60 allocations/second per widget; across a list of 20 visible items it is 1 200 allocations/second, creating measurable GC pressure (MEDIUM inside animations or list items)
• BoxDecoration(borderRadius: BorderRadius.circular(8), boxShadow: [...]) inline in a list item's build() — multiplied across visible items on every scroll-driven rebuild (MEDIUM)
• Objects that never change should not be constructed in build() regardless of rebuild frequency

Unified fix: promote to static const, a const constructor call at the call site, or a final field initialized in initState():

// VIOLATION — new TextStyle allocated on every animation frame
class AnimatedLabel extends AnimatedWidget {
  @override
  Widget build(BuildContext context) {
    return Text(
      label,
      style: TextStyle(fontSize: 14, color: Colors.red), // allocates every frame
    );
  }
}

// CORRECT — single allocation, reused across all rebuilds
class AnimatedLabel extends AnimatedWidget {
  static const _labelStyle = TextStyle(fontSize: 14, color: Colors.red);

  @override
  Widget build(BuildContext context) {
    return Text(label, style: _labelStyle);
  }
}

---

### Step 7 — Detect missing const constructors

> Feeds: Technical Debt Indicators

`const` widgets are canonicalized by the Dart compiler and Flutter framework — the same `const` instance is reused across rebuilds, skipping the build, layout, and paint phases for that subtree entirely.

The impact of `const` is proportional to the **size of the subtree** it covers. A `const Text("Submit")` saves trivial work. A `const` subtree covering an entire section of a form saves significant work.

Search for `const`-eligible but non-const widget instantiations:

```bash
# Find const constructors that exist but are not being used
flutter analyze --no-fatal-warnings 2>&1 | grep "prefer_const_constructors\|prefer_const_literals"

Also manually check:

• EdgeInsets.all(8) used repeatedly — should be const EdgeInsets.all(8) — each non-const call allocates a new object
• Widget classes that accept only final fields and have no non-const dependencies — should declare const constructor
• Padding(padding: EdgeInsets.symmetric(...), child: ...) patterns where all values are literals — entire subtree can be const
• Icon(Icons.home), SizedBox(height: 16), Divider() without const — frequently instantiated, always const-eligible

The highest-impact const opportunity is not leaf widgets like Text — it's widget subtrees that are structural (spacers, dividers, icon buttons, empty states, static headers) that appear across many screens.

---

Step 8 — Detect unnecessary StatefulWidgets and misplaced local state

Feeds: Technical Debt Indicators, Critical Performance Issues

This step has two sub-problems that are opposite in nature:

Sub-problem A — StatefulWidget that should be StatelessWidget:

grep -rn "extends StatefulWidget" lib/ --include="*.dart"

For each match, open the file and check:

• Does _State class have any final or mutable fields beyond late overrides?
• Does it call setState?
• Does it use initState, dispose, didUpdateWidget, or didChangeDependencies?

If none of the above: convert to StatelessWidget. Unnecessary StatefulWidgets create an extra State object and an extra element in the element tree.

Sub-problem B (higher severity) — StatefulWidget managing business state with setState:

This is the opposite problem and more damaging. Look for StatefulWidgets where setState is called in response to:

• async operations (API calls, future completions)
• user interactions that affect multiple widgets or screens
• data that should survive navigation

This state belongs in a Bloc/Cubit or equivalent, not in widget-local setState. setState for this type of state causes:

• full widget rebuild on every operation
• state loss on widget disposal / navigation
• untestable business logic

Signal to look for:

grep -rn "setState" lib/ --include="*.dart" -l
# Then open each file and check if setState is wrapping async logic or data fetching

---

Step 9 — Detect implicit saveLayer() calls and RepaintBoundary misuse

Feeds: Critical Performance Issues

This is the most commonly overlooked performance issue in Flutter. saveLayer() is a GPU operation that allocates an offscreen render target and flushes the current render pipeline — it is the single most expensive operation in the Flutter rendering pipeline. It is triggered implicitly by several common widgets.

Search for implicit saveLayer() triggers:

grep -rn "Opacity\|BackdropFilter\|ShaderMask\|ColorFiltered\|ImageFilter" lib/ --include="*.dart"
grep -rn "boxShadow.*borderRadius\|borderRadius.*boxShadow" lib/ --include="*.dart"

HIGH severity — Opacity with animated or frequently-changing value:

• Opacity(opacity: _animationValue) driven by an AnimationController — calls saveLayer() on every animation frame (60-120 times/second)
• Replace with FadeTransition(opacity: animation) — operates in the compositing layer, completely avoids saveLayer()
• AnimatedOpacity is also acceptable for state-driven fades (not frame-driven animations)

HIGH severity — BackdropFilter:

• BackdropFilter always forces saveLayer(). Use sparingly. Never inside ListView.builder items.

MEDIUM severity — ClipRRect / ClipOval / PhysicalModel:

• These force a compositing layer on every repaint of the clipped widget. When used on a widget that rebuilds frequently, they are significant.
• Replace ClipRRect with decoration: BoxDecoration(borderRadius: ...) when possible — no compositing layer required.

MEDIUM severity — BoxDecoration with both boxShadow and borderRadius:

• This combination forces a saveLayer() to correctly composite the shadow under the rounded corners.

RepaintBoundary — missing isolation: Flutter repaints all dirty widgets within a single repaint boundary together. Adding RepaintBoundary around:

• animated widgets (spinners, progress bars, lottie animations)
• frequently-updating widgets (timers, live data feeds, video frames)
• complex static subtrees alongside dynamic content

...isolates their repaints so the rest of the tree is not affected.

grep -rn "RepaintBoundary" lib/ --include="*.dart"

If RepaintBoundary is entirely absent and the app has animations or live-updating widgets, flag it as an optimization opportunity.

---

Evaluation Criteria

Evaluate UI performance across five dimensions. Each dimension contributes to the final Performance Score.

---

Rebuild Efficiency

Measures whether state changes trigger minimal widget rebuilds.

Frame budget context: At 60fps the rendering pipeline has 16ms per frame. At 120fps it has 8ms. Unnecessary rebuilds consume this budget before layout and paint even begin.

Signals of good rebuild efficiency:

• BlocBuilder always has buildWhen to skip irrelevant state emissions
• BlocSelector used when only a single field of the state is needed
• context.select<X, T>(...) used instead of context.watch<X>() for granular Provider/Riverpod rebuilds
• AnimatedBuilder wraps only the smallest animated leaf widget, not the full screen
• RepaintBoundary present around frequently-animating or frequently-updating widgets

Signals of poor rebuild efficiency:

• BlocBuilder without buildWhen on widgets that cover a full screen
• setState called in response to async operations on a StatefulWidget that owns large subtrees
• context.watch<X>() on a widget that only uses one field of X
• No RepaintBoundary isolating animated widgets (spinner, progress indicator, video, lottie) from static content
• Nested BlocBuilder / Consumer widgets where the outer one already triggers a full rebuild

---

Widget Tree Complexity

Measures depth and layout cost of the widget hierarchy.

Signals of good complexity:

• build() methods under 50 lines
• Sub-widgets extracted as const-eligible classes
• Padding / ColoredBox / DecoratedBox used instead of Container when only one property is needed
• No IntrinsicHeight or IntrinsicWidth inside scrollable containers

Signals of poor complexity:

• build() methods over 100 lines with deeply nested layout wrappers
• IntrinsicHeight or IntrinsicWidth inside ListView.builder items (O(n²) layout)
• Container used as a multi-purpose wrapper when a single-purpose widget suffices
• Wrap with many children inside a scrollable (two-pass layout on every rebuild)

---

Scroll Performance

Measures how efficiently scrolling lists are implemented.

Signals of good scroll performance:

• ListView.builder / GridView.builder for all dynamic content
• itemExtent or prototypeItem set when all items share the same height
• List item widgets are const-constructible or lightweight
• No ClipRRect with borderRadius on individual list items
• Image widgets in lists specify cacheWidth / cacheHeight

Signals of poor scroll performance:

• Column(children: list.map(...).toList()) inside SingleChildScrollView — no lazy loading
• ListView(children: [...]) with dynamic or large content sets
• shrinkWrap: true inside a scroll view — defeats lazy loading
• ClipRRect or BoxDecoration with shadow + borderRadius on list items — saveLayer() per item
• Image.network without cacheWidth/cacheHeight in list items

---

Layout Efficiency

Measures layout calculation cost per frame.

Flutter's layout protocol: Constraints flow down, sizes flow up. Most layout widgets are O(1). Violations of this rule create O(n) or O(n²) layout.

Signals of good layout efficiency:

• Layout widgets used for their specific single purpose (Padding, Align, SizedBox, Expanded)
• No multi-pass layout widgets (IntrinsicHeight, IntrinsicWidth, CustomMultiChildLayout) in hot paths
• CustomPainter used for complex drawing instead of composing many layout widgets

Signals of poor layout efficiency:

• IntrinsicHeight / IntrinsicWidth in scrollable contexts (documented O(n²) worst case)
• 5+ nested layout wrappers to achieve what a single Padding + DecoratedBox could accomplish
• Offstage used to hide widgets — they still participate in layout even when invisible. Use conditional rendering instead.
• Visibility(visible: false) without maintainSize: false — hidden widgets still consume layout space

---

Rendering Stability

Measures risk of dropped frames from rendering-pipeline bottlenecks.

The most common source of rendering jank that escapes code review is implicit saveLayer() calls — GPU operations that flush the render pipeline and allocate offscreen buffers.

Signals of good rendering stability:

• FadeTransition used for opacity animations (compositing layer, no saveLayer())
• RepaintBoundary isolates heavy animating subtrees
• ClipRRect replaced with BoxDecoration(borderRadius: ...) where possible
• Animations use AnimatedWidget or Tween.animate() at leaf level, not driving setState at parent level

Signals of poor rendering stability:

• Opacity(opacity: animValue) with a continuously-changing value — saveLayer() every frame
• BackdropFilter used in list items or frequently-rebuilt widgets
• ShaderMask or ColorFiltered applied to large subtrees that update frequently
• BoxDecoration with boxShadow + borderRadius on items that repaint frequently
• No RepaintBoundary around animated widgets that live alongside heavy static content

---

Performance Maturity Levels

Classify the UI performance maturity. The level directly determines the base Performance Score range.

---

Level 1 — High Jank Risk

Score range: 1–3

UI architecture likely to cause frequent dropped frames. Non-lazy lists, missing const widgets, saveLayer() triggers in scroll views, and setState managing screen-level state are all present.

---

Level 2 — Basic Performance

Score range: 4–5

UI generally functional but contains several performance risks. Lazy lists present on most screens but BlocBuilder lacks buildWhen, rebuild scopes are large, or IntrinsicHeight appears in lists.

---

Level 3 — Optimized UI

Score range: 6–8

Good rebuild isolation, ListView.builder used consistently, no IntrinsicHeight in hot paths, const used broadly. Some saveLayer() triggers may remain. Score within band depends on whether RepaintBoundary is used and whether BlocBuilder has buildWhen.

---

Level 4 — Production Performance

Score range: 9–10

Highly optimized UI. RepaintBoundary isolates animated subtrees. No implicit saveLayer() in hot paths. FadeTransition used over Opacity for animations. BlocBuilder scoped with buildWhen or replaced by BlocSelector where applicable. const constructors present throughout.

---

Output Format

Produce the report using the following template. Output as formatted Markdown matching the structure below exactly.

The Performance Score (1–10) is derived from the Maturity Level band adjusted by evidence:

• Start from the midpoint of the Maturity Level range
• +1 if no HIGH severity issues are found
• -1 for each additional HIGH severity issue beyond one
• +0.5 if BlocBuilder has buildWhen consistently across the codebase
• -0.5 if saveLayer() triggers (Opacity animation, BackdropFilter) found in scroll views
• -0.5 if IntrinsicHeight or IntrinsicWidth found inside ListView.builder items

Round to the nearest integer. Minimum 1, maximum 10.

---

# Flutter Widget Performance Audit

## Performance Score

X / 10

## Performance Maturity Level

Level [1–4] — [Label]

## Key Performance Strengths

- [strength 1]
- [strength 2]

## Critical Performance Issues

### Issue 1

**Severity:** HIGH / MEDIUM / LOW

**Problem**
[Description with file reference where possible]

**Impact**
[UI performance consequence — be specific: "causes saveLayer() on every animation frame", "defeats lazy loading", etc.]

**Recommendation**
[Concrete optimization with code pattern where applicable]

### Issue 2

[Repeat structure]

## Technical Debt Indicators

- [large build() methods]
- [missing const widgets]
- [unnecessary StatefulWidgets]
- [missing RepaintBoundary]

## Strategic Performance Recommendations

1. [highest impact optimization]
2. [second recommendation]
3. [third recommendation]

---

Common Pitfalls

Avoid these mistakes when running the audit:

• Do not flag saveLayer() triggers in rarely-used screens. BackdropFilter on a settings modal that opens once per session is not a production concern. Focus on hot paths: ListView.builder items, home screen, and any animation loop.
• Do not penalize IntrinsicHeight in non-scrollable contexts. It's only a problem inside ListView.builder or other lazy scroll containers where it's applied to every item.
• Do not flag StatefulWidget as unnecessary without checking the full State class. AnimationController, TabController, ScrollController, FocusNode, and TextEditingController all require initState/dispose and legitimately need StatefulWidget.
• Do not flag Opacity(opacity: 0.0) as a saveLayer() issue. Flutter short-circuits Opacity at exactly 0.0 and 1.0 — no saveLayer() is triggered at these values.
• Do not recommend RepaintBoundary universally. Each RepaintBoundary allocates a compositing layer. Adding too many actually degrades performance. Only recommend where a frequently-repainting widget is surrounded by static content.
• Do not flag generated files. *.g.dart, *.freezed.dart, and any files under generated/ are not developer-authored widget code.

---

Rules

The agent must:

• read the full widget tree structure and scan for the patterns described in each step before drawing conclusions
• identify performance issues based on real code patterns found in the project
• prioritize issues by potential runtime impact (saveLayer in hot paths > missing const on leaf widgets)
• reference specific files or patterns observed when describing issues

The agent must NOT:

• modify files
• rewrite widgets
• propose full UI rewrites
• flag theoretical issues not evidenced in the actual codebase

This skill is intended only for performance analysis of Flutter UI layers.

---

Reference Guide

Consult these files during analysis to validate findings and assign severity scores accurately.

File	Content
./references/rebuild-patterns.md	BlocBuilder+buildWhen, BlocSelector, context.select, setState scope, AnimationController rebuild isolation, RepaintBoundary for rebuild containment
./references/savelayer-and-compositing.md	Implicit saveLayer() triggers (Opacity, BackdropFilter, ShaderMask, ClipRRect, BoxDecoration), FadeTransition vs Opacity, RepaintBoundary placement guide
./references/scroll-performance.md	Lazy loading variants, shrinkWrap anti-pattern, Column+map in SingleChildScrollView, itemExtent, image cache sizing, nested scrollables
./references/layout-cost.md	IntrinsicHeight/IntrinsicWidth O(n²), Wrap two-pass cost, Container vs specific widgets, Offstage hidden layout cost, MediaQuery.of over-registration