axiom-energy-diag by CharlesWiltgen

---
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
- [ ] Device plugged in? (Power metrics show 0)
- [ ] Debug build? (Less optimized than release)
- [ ] Low Power Mode on? (May affect measurements)

### 5-Minute Check (Power Profiler)
- [ ] Which subsystem is dominant? (CPU/GPU/Network/Display)
- [ ] Sustained or spiky?
- [ ] Foreground or background?

### 15-Minute Investigation
- [ ] If CPU: Run Time Profiler to identify function
- [ ] If Network: Check request frequency and size
- [ ] If GPU: Check animation frame rates
- [ ] If Background: Check Info.plist modes

### 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+