Skip to content

Performance Loop

Salman Ashraf edited this page Oct 9, 2026 · 1 revision

Performance Loop

Performance is a first-class Mobile AI Agents loop. Use it when a mobile app is slow, janky, freezing, leaking memory, draining battery, using too much network, or growing too large.

The loop is evidence-first: measure the symptom, choose the right agent or skill, apply the smallest fix, re-measure, save the baseline, and monitor for regressions.


What It Covers

Area Symptoms Best Starting Point
Startup Cold start, hot start, slow splash, app open delay @PERF, /perf-audit
ANR Frozen UI, input timeout, Play Console ANR @FREEZE, /anr-investigation
Memory leaks Retained Fragment/View/Activity, growing heap, OOM @RETAINER, /memory-leak-investigation
Frame drops / jank Slow scroll, dropped frames, animation stutter @PERF, /perf-audit, platform reviewer
Battery High CPU wakeups, background work, location abuse @PERF, /perf-audit
Network Chatty requests, large payloads, retry storms @PERF, /perf-audit
Bundle / app size Large APK/AAB/IPA, slow download, bloated assets @PERF, /perf-audit
Slow screens Heavy render, blocking IO, expensive lists @PERF, /perf-audit
Regression monitoring Performance gets worse after a PR or release perf-sprint, Mobile Harness

Agent And Skill Map

Need Agent Or Skill Use It For
Broad performance diagnosis @PERF Find bottlenecks, prioritize fixes, define measurements
Android ANR investigation @FREEZE, /anr-investigation Thread, lock, binder, and timeout analysis
Android memory leak analysis @RETAINER, /memory-leak-investigation LeakCanary reference path and lifecycle ownership
Screen-level profiling /perf-audit Main thread, rendering, memory, list, and fix ranking
Compose UI jank /compose-review, compose-ui-reviewer Recomposition, LazyColumn keys, effects, state stability
Flutter rebuilds /flutter-review, @DART Widget rebuilds, state, layout, async handling
React Native re-renders performance-optimizer, /rn-performance, @BRIDGE React memoization, FlatList, bridge hot paths
Unity frame budget @FORGE, /game-perf Update loops, GC allocations, draw calls, physics
Device validation /mobile-mcp-qa, device-proof-report Verify performance-sensitive flows on a target device
Delivery orchestration @MOBILE-HARNESS, perf-sprint Run checks after implementation and save evidence

Loop Steps

1. IDENTIFY SYMPTOM
   -> Startup, ANR, memory leak, jank, battery, network, size, or slow screen.

2. COLLECT EVIDENCE
   -> Device model, OS, app version, commit, user flow, baseline numbers, traces, screenshots, logs.

3. CHOOSE ROUTE
   -> Select the smallest matching agent or skill from the map.

4. ANALYZE ROOT CAUSE
   -> Name the hot function, blocked thread, retained owner, expensive render path, or oversized asset.

5. APPLY SMALLEST SAFE FIX
   -> Change one bottleneck at a time so improvement can be attributed.

6. VERIFY WITH MEASUREMENTS
   -> Re-run the same flow on the same target and compare before/after numbers.

7. SAVE PERFORMANCE BASELINE
   -> Write `PERFORMANCE_AUDIT_REPORT.md` and store trace/screenshot links.

8. MONITOR REGRESSIONS
   -> Add a test, CI threshold, release gate, or follow-up task when possible.

Evidence To Collect

Platform Evidence
Android Play Console ANR cluster, traces.txt, Perfetto/Systrace, Android Studio Profiler, LeakCanary trace, APK Analyzer output, device model, API level
iOS Instruments Time Profiler, Core Animation, Allocations/Leaks, MetricKit, Xcode Organizer reports, device model, iOS version
Flutter Flutter DevTools Performance and Memory tabs, rebuild counts, timeline flame chart, package size output
React Native React DevTools Profiler, Flipper Perf Monitor, Hermes profile, Metro bundle size, native traces
Unity Unity Profiler, frame debugger, memory snapshot, draw call count, texture memory, target device
Unreal Unreal Insights, stat unit, stat game, stat RHI, render thread timing, packaged build size

If there is no baseline, the result is BLOCKED or UNKNOWN. Do not claim a performance fix without re-measuring.


Android Examples

ANR During Startup

Symptom: Play Console reports "Input dispatching timed out" during app launch.
Evidence: ANR trace shows main thread blocked in RoomDatabase.query().
Route: @FREEZE + /anr-investigation.
Fix: Move startup database read to Dispatchers.IO and defer non-critical initialization.
Verify: Compare cold start time and confirm no main-thread DB query appears in trace.
Report: PERFORMANCE_AUDIT_REPORT.md with ANR cluster link, before/after startup time, and trace links.

Fragment Memory Leak

Symptom: Heap grows after opening and closing ProfileFragment.
Evidence: LeakCanary shows RecyclerView retaining ProfileAdapter, which retains Fragment views.
Route: @RETAINER + /memory-leak-investigation.
Fix: Clear RecyclerView adapter in onDestroyView() and remove view references from adapter callbacks.
Verify: Reopen/close ProfileFragment five times and confirm LeakCanary no longer reports retained Fragment.
Report: PERFORMANCE_AUDIT_REPORT.md with retained size before/after and LeakCanary evidence.

Cross-Platform Examples

Platform Symptom Route Verification
iOS Slow SwiftUI list scroll @PERF, @SWIFT, /ios-performance Instruments Core Animation frame times improve
Flutter Product grid rebuilds every item @DART, /flutter-review, /perf-audit DevTools shows fewer rebuilds and frame times under 16ms
React Native Feed drops frames on like button performance-optimizer, /rn-performance React Profiler shows fewer row renders
Unity Mobile level spikes GC every few seconds @FORGE, /game-perf Unity Profiler shows no hot-path GC.Alloc spikes
Unreal Blueprint Tick runs expensive logic @UNREAL, /game-perf Unreal Insights shows reduced game thread time

Report Format

Create:

PERFORMANCE_AUDIT_REPORT.md

Use this deterministic format:

# Performance Audit Report

## Summary
Result: PASS | FAIL | BLOCKED
Platform:
Device:
OS Version:
App Version:
Commit:
Flow:
Performance Area: Startup | ANR | Memory | Frame | Battery | Network | Size | Slow Screen | Regression

## Baseline
| Metric | Before | Target | Evidence |
|---|---:|---:|---|

## Findings
| ID | Severity | Area | Evidence | Root Cause | Fix Summary |
|---|---|---|---|---|---|

## Finding Details
### PERF-001 - <short title>
- Severity:
- Area:
- Evidence:
- Root Cause:
- Fix:
- Verification:
- Regression Guard:

## Changes Made
| File | Change | Reason |
|---|---|---|

## Verification
| Metric | Before | After | Result | Evidence |
|---|---:|---:|---|---|

## Device Or Trace Evidence
- <trace, screenshot, profiler export, issue, or report link>

## Regression Monitoring
- <test, CI threshold, dashboard, alert, or follow-up issue>

## Next Actions
1. <highest priority next fix or "None">
2. <next fix or "None">
3. <next fix or "None">

Pass/Fail Rules

  • PASS: The measured bottleneck improved or meets target, and evidence is attached.
  • FAIL: The bottleneck remains, got worse, or lacks a safe fix.
  • BLOCKED: Required evidence, device, build, credentials, or profiler access is missing.

Performance work is complete only when the report includes before/after measurements and a regression monitoring decision.

Clone this wiki locally