Repository navigation
Performance Loop
Salman Ashraf edited this page Oct 9, 2026
·
1 revision
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.
| 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 |
| 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 |
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.
| 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.
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.
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.
| 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 |
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: 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.
Getting Started
Documentation
- All Documentation
- Installation
- Figma MCP and Design Handoff
- Figma Spec Tools
- Core Loops
- Mobile Engineering Loop
- Mobile Memory
- Performance Loop
Reference
- Agents
- Platform Guide
- Skills and Prompts
- Android Device QA Setup
- Mobile App Design Skill
- Mobile Harness
- Enterprise Mobile Harness
- Workflows
- Reference
Community
Repository github.com/salmanashraf/mobile-ai-agents
Version: v1.0.38 · MIT License