| name | axiom-energy-diag |
| description | Symptom-based energy troubleshooting - decision trees for 'app at top of battery settings', 'phone gets hot', 'background drain', 'high cellular usage', with time-cost analysis for each diagnosis path |
| license | MIT |
| metadata | {"version":"1.0.0"} |
Energy Diagnostics
Symptom-based troubleshooting for energy issues. Start with your symptom, follow the decision tree, get the fix.
Related skills: axiom-energy (patterns, checklists), axiom-energy-ref (API reference)
Symptom 1: App at Top of Battery Settings
Users or you notice your app consuming significant battery.
Diagnosis Decision Tree
App at top of Battery Settings?
│
├─ Step 1: Run Power Profiler (15 min)
│ ├─ CPU Power Impact high?
│ │ ├─ Continuous? → Timer leak or polling loop
│ │ │ └─ Fix: Check timers, add tolerance, convert to push
│ │ └─ Spikes during actions? → Eager loading or repeated parsing
│ │ └─ Fix: Use LazyVStack, cache parsed data
│ │
│ ├─ Network Power Impact high?
│ │ ├─ Many small requests? → Batching issue
│ │ │ └─ Fix: Batch requests, use discretionary URLSession
│ │ └─ Regular intervals? → Polling pattern
│ │ └─ Fix: Convert to push notifications
│ │
│ ├─ GPU Power Impact high?
│ │ ├─ Animations? → Running when not visible
│ │ │ └─ Fix: Stop in viewWillDisappear
│ │ └─ Blur effects? → Over dynamic content
│ │ └─ Fix: Remove or use static backgrounds
│ │
│ └─ Display Power Impact high?
│ └─ Light backgrounds on OLED?
│ └─ Fix: Implement Dark Mode (up to 70% savings)
│
└─ Step 2: Check background section in Battery Settings
├─ High background time?
│ ├─ Location icon visible? → Continuous location
│ │ └─ Fix: Switch to significant-change monitoring
│ ├─ Audio active? → Session not deactivated
│ │ └─ Fix: Deactivate audio session when not playing
│ └─ BGTasks running long? → Not completing promptly
│ └─ Fix: Call setTaskCompleted sooner
│
└─ Background time appropriate?
└─ Issue is in foreground usage → Focus on CPU/GPU fixes above
Time-Cost Analysis
| Approach | Time | Accuracy |
|---|
| Run Power Profiler, identify subsystem | 15-20 min | High |
| Guess and optimize random areas | 4+ hours | Low |
| Read all code looking for issues | 2+ hours | Medium |
Recommendation: Always use Power Profiler first. It costs 15 minutes but guarantees you optimize the right subsystem.
Symptom 2: Device Gets Hot
Device temperature increases noticeably during app use.
Diagnosis Decision Tree
Device gets hot during app use?
│
├─ Hot during specific action?
│ │
│ ├─ During video/camera use?
│ │ ├─ Video encoding? → Expected, but check efficiency
│ │ │ └─ Fix: Use hardware encoding, reduce resolution if possible
│ │ └─ Camera active unnecessarily? → Not releasing session
│ │ └─ Fix: Call stopRunning() when done
│ │
│ ├─ During scroll/animation?
│ │ ├─ GPU-intensive effects? → Blur, shadows, many layers
│ │ │ └─ Fix: Reduce effects, cache rendered content
│ │ └─ High frame rate? → Unnecessary 120fps
│ │ └─ Fix: Use CADisplayLink preferredFrameRateRange
│ │
│ └─ During data processing?
│ ├─ JSON parsing? → Repeated or large payloads
│ │ └─ Fix: Cache parsed results, paginate
│ └─ Image processing? → Synchronous on main thread
│ └─ Fix: Move to background, cache results
│
├─ Hot during normal use (no specific action)?
│ │
│ ├─ Run Power Profiler to identify:
│ │ ├─ CPU high continuously → Timer, polling, tight loop
│ │ ├─ GPU high continuously → Animation leak
│ │ └─ Network high continuously → Polling pattern
│ │
│ └─ Check for infinite loops or runaway recursion
│ └─ Use Time Profiler in Instruments
│
└─ Hot only in background?
├─ Location updates continuous? → High accuracy or no stop
│ └─ Fix: Reduce accuracy, stop when done
├─ Audio session active? → Hardware kept powered
│ └─ Fix: Deactivate when not playing
└─ BGTask running too long? → System may throttle
└─ Fix: Complete tasks faster, use requiresExternalPower
Time-Cost Analysis
| Approach | Time | Outcome |
|---|
| Power Profiler + Time Profiler | 20-30 min | Identifies exact cause |
| Check code for obvious issues | 1-2 hours | May miss non-obvious causes |
| Wait for user complaints | N/A | Reputation damage |
Symptom 3: Background Battery Drain
App drains battery even when user isn't actively using it.
Diagnosis Decision Tree
High background battery usage?
│
├─ Step 1: Check Info.plist background modes
│ │
│ ├─ "location" enabled?
│ │ ├─ Actually need background location?
│ │ │ ├─ YES → Use significant-change, lowest accuracy
│ │ │ └─ NO → Remove background mode, use when-in-use only
│ │ └─ Check: Is stopUpdatingLocation called?
│ │
│ ├─ "audio" enabled?
│ │ ├─ Audio playing? → Expected
│ │ ├─ Audio NOT playing? → Session still active
│ │ │ └─ Fix: Deactivate session, use autoShutdownEnabled
│ │ └─ Playing silent audio? → Anti-pattern for keeping app alive
│ │ └─ Fix: Use proper background API (BGTask)
│ │
│ ├─ "fetch" enabled?
│ │ └─ Check: Is earliestBeginDate reasonable? (not too frequent)
│ │
│ └─ "remote-notification" enabled?
│ └─ Expected for push updates, check didReceiveRemoteNotification efficiency
│
├─ Step 2: Check BGTaskScheduler usage
│ │
│ ├─ BGAppRefreshTask scheduled too frequently?
│ │ └─ Fix: Increase earliestBeginDate interval
│ │
│ ├─ BGProcessingTask not using requiresExternalPower?
│ │ └─ Fix: Add requiresExternalPower = true for non-urgent work
│ │
│ └─ Tasks not completing? (setTaskCompleted not called)
│ └─ Fix: Always call setTaskCompleted, implement expirationHandler
│
└─ Step 3: Check beginBackgroundTask usage
│
├─ endBackgroundTask called promptly?
│ └─ Fix: Call immediately after work completes, not at expiration
│
└─ Multiple overlapping background tasks?
└─ Fix: Track task IDs, ensure each is ended
Common Background Drain Patterns
| Pattern | Power Profiler Signature | Fix |
|---|
| Continuous location | CPU lane + location icon | significant-change |
| Audio session leak | CPU lane steady | setActive(false) |
| Timer not invalidated | CPU spikes at intervals | invalidate in background |
| Polling from background | Network lane at intervals | Push notifications |
| BGTask too long | CPU sustained | Faster completion |
Time-Cost Analysis
| Approach | Time | Outcome |
|---|
| Check Info.plist + BGTask code | 30 min | Finds common issues |
| On-device Power Profiler trace | 1-2 hours (real usage) | Captures real behavior |
| User-collected trace | Variable | Best for unreproducible issues |
Symptom 4: High Energy Only on Cellular
Battery drains faster on cellular than WiFi.
Diagnosis Decision Tree
High battery drain on cellular only?
│
├─ Expected: Cellular radio uses more power than WiFi
│ └─ But: Excessive drain indicates optimization opportunity
│
├─ Check URLSession configuration
│ │
│ ├─ allowsExpensiveNetworkAccess = true (default)?
│ │ └─ Fix: Set to false for non-urgent requests
│ │
│ ├─ isDiscretionary = false (default)?
│ │ └─ Fix: Set to true for background downloads
│ │
│ └─ waitsForConnectivity = false (default)?
│ └─ Fix: Set to true to avoid failed connection retries
│
├─ Check request patterns
│ │
│ ├─ Many small requests? → High connection overhead
│ │ └─ Fix: Batch into fewer larger requests
│ │
│ ├─ Polling? → Radio stays active
│ │ └─ Fix: Push notifications
│ │
│ └─ Large downloads in foreground? → Could wait for WiFi
│ └─ Fix: Use background URLSession with discretionary
│
└─ Check Low Data Mode handling
├─ Respecting allowsConstrainedNetworkAccess?
│ └─ Fix: Set to false for non-essential requests
│
└─ Checking ProcessInfo.processInfo.isLowDataModeEnabled?
└─ Fix: Reduce payload sizes, defer non-essential transfers
Time-Cost Analysis
| Approach | Time | Outcome |
|---|
| Review URLSession configs | 15 min | Quick wins |
| Add discretionary flags | 30 min | Significant savings |
| Convert poll to push | 2-4 hours | Largest impact |
Symptom 5: Energy Spike During Specific Action
Noticeable battery drain or heat when performing particular operation.
Diagnosis Decision Tree
Energy spike during specific action?
│
├─ Step 1: Record Power Profiler during action
│ └─ Note which subsystem spikes (CPU/GPU/Network/Display)
│
├─ CPU spike?
│ │
│ ├─ Is it parsing data?
│ │ ├─ Same data parsed repeatedly?
│ │ │ └─ Fix: Cache parsed results (lazy var)
│ │ └─ Large JSON/XML payload?
│ │ └─ Fix: Paginate, stream parse, or use binary format
│ │
│ ├─ Is it creating views?
│ │ ├─ Many views at once?
│ │ │ └─ Fix: Use LazyVStack/LazyHStack
│ │ └─ Complex view hierarchies?
│ │ └─ Fix: Simplify, use drawingGroup()
│ │
│ └─ Is it image processing?
│ ├─ On main thread?
│ │ └─ Fix: Move to background queue
│ └─ No caching?
│ └─ Fix: Cache processed images
│
├─ GPU spike?
│ │
│ ├─ Starting animation?
│ │ └─ Fix: Ensure frame rate appropriate
│ │
│ ├─ Showing blur effect?
│ │ └─ Fix: Use solid color or pre-rendered blur
│ │
│ └─ Complex render? (shadows, masks, many layers)
│ └─ Fix: Simplify, use shouldRasterize, cache
│
├─ Network spike?
│ │
│ ├─ Large download started?
│ │ └─ Fix: Use background URLSession, show progress
│ │
│ ├─ Many parallel requests?
│ │ └─ Fix: Limit concurrency, batch
│ │
│ └─ Retrying failed requests?
│ └─ Fix: Exponential backoff, waitsForConnectivity
│
└─ Display spike?
└─ Unusual unless changing brightness programmatically
└─ Fix: Don't modify brightness, let system control
Time-Cost Analysis
| Approach | Time | Outcome |
|---|
| Power Profiler during action | 5-10 min | Identifies subsystem |
| Time Profiler for CPU details | 10-15 min | Identifies function |
| Code review without profiling | 1+ hours | May miss actual cause |
Quick Diagnostic Checklist
Use this when you need fast answers:
30-Second Check
5-Minute Check (Power Profiler)
15-Minute Investigation
Common Quick Fixes
| Finding | Quick Fix | Time |
|---|
| Timer without tolerance | Add .tolerance = 0.1 | 1 min |
| VStack with large ForEach | Change to LazyVStack | 1 min |
| allowsExpensiveNetworkAccess = true | Set to false | 1 min |
| Missing stopUpdatingLocation | Add stop call | 2 min |
| No Dark Mode | Add asset variants | 30 min |
| Audio session always active | Add setActive(false) | 5 min |
When to Escalate
Use axiom-energy skill when
- Need full audit checklist
- Want comprehensive patterns with code
- Planning proactive optimization
Use axiom-energy-ref skill when
- Need specific API details
- Want complete code examples
- Implementing from scratch
Use energy-auditor agent when
- Want automated codebase scan
- Looking for anti-patterns at scale
- Pre-release energy audit
Run: /axiom:audit energy
Last Updated: 2025-12-26
Platforms: iOS 26+, iPadOS 26+
