# Worked Examples Three end-to-end diagnostic scenarios run through mac-ops. Each shows the symptom, the script sequence, the actual signal in the output, and the fix. Treat these as patterns to recognize — they cover the most common Mac complaints in 2026. ## Example 1: "My Mac is slow and feels hot" ### Symptom User reports: "Mac is sluggish. Fans run constantly even when I'm not doing anything. Battery drains faster than it used to." ### Diagnostic sequence ```bash scripts/health-audit.sh --days 7 ``` Expected verdict pattern: ``` === 5. RESOURCE PRESSURE (snapshot) === Top 5 by CPU%: 63.2% [ 582] mds_stores 21.4% [ 328] mds 18.1% [ 367] WindowServer ... [WARN] mds_stores CPU :: 63.2% — sustained spike? === 6. WAKE PATTERN (last 24h) === [WARN] Wakes in pmset log (full history) :: 1247 — drill with wake-reasons.sh ``` Two signals: heavy Spotlight + lots of wakes. Drill: ```bash scripts/spotlight-status.sh scripts/wake-reasons.sh --since 7d ``` Spotlight typically shows one of three causes: - **Heavy ongoing reindex** (new external volume mounted recently) - **Indexing a path it shouldn't** (large dev folders, node_modules, .git) - **Corrupt index** (mds_stores spinning on the same file forever) For the third case, the fix is brutal but effective: ```bash sudo mdutil -E / # nuke + rebuild index ``` Plan for 1-4 hours of high mds_stores CPU after this; it's the rebuild. After that, idle CPU should return. Wake-reasons typically shows: ``` rtc scheduled | 115 | 11% (rtc/Maintenance) ← Power Nap wifi/bluetooth | 111 | 11% (wlan/) ← Wi-Fi proximity wake push-svc wake | 76 | 7% (rtc/SleepService) ← push notification maintenance ``` The fix is in System Settings → Battery → Options: - Power Nap: Off (especially on battery) - Wake for network access: Off ### Why this presents as "slow + hot" When a Mac wakes for "maintenance" hundreds of times overnight, the SoC spends fractional CPU keeping things warm. Daytime, the user perceives the heat lingering. Over a week, battery cycle count creeps up. --- ## Example 2: "I can't share my screen on Zoom anymore" ### Symptom User reports: "Zoom worked yesterday. Today the screen-share button just doesn't do anything. No prompt appears." ### Diagnostic sequence This is the textbook TCC denial. Bypassed via: ```bash scripts/tcc-audit.sh -a zoom --denied ``` Expected output: ``` === 2. PERMISSION GRANTS === service | client | auth | last modified -----------------------------|----------------------------------------------------|------|------------------------ kTCCServiceScreenCapture | us.zoom.xos | DENY | 2026-05-15 04:12:00 ``` The DENY row tells the whole story: Zoom's Screen Recording permission was revoked. Common causes: - macOS update reset the grant - User clicked "Don't Allow" on a prompt - An MDM profile revoked it ### Fix ```bash tccutil reset ScreenCapture us.zoom.xos ``` Then re-open Zoom and attempt screen share — macOS prompts; user approves; permission persists. If the user is on a managed Mac and tccutil shows the grant has `auth_reason = 6` (MDM-set), they need to contact IT to amend the configuration profile. ### Cross-verification ```bash scripts/health-audit.sh ``` Rung 7 (TCC) will now show: ``` [WARN] User TCC grants (denied) :: 3 — drill with tcc-audit.sh ``` If that count was elevated before the Zoom fix and dropped after, you've confirmed the same kind of denial pattern. --- ## Example 3: "Macintosh HD is full but I deleted everything" ### Symptom User reports: "About This Mac says I have 4 GB free out of 500 GB. I just emptied the Trash and the number didn't move." ### Diagnostic sequence ```bash scripts/storage-pressure.sh -v / ``` Expected output: ``` === 1. df vs APFS reality === /dev/disk3s1s1 460Gi 456Gi 4.0Gi 99% ... / diskutil info (APFS-aware): Container Free Space: 103.0 GB ← significantly more than df shows APFS Snapshots are defined upon this APFS Volume. === 2. APFS SNAPSHOTS === [WARN] Local Time Machine snapshots :: 42 — purgeable space tied up === 4. CACHE / TEMPORARY DIRECTORIES === User caches: /Users/.../Library/Caches = 87 GB ← Docker, browser caches, Spotify, etc. ``` Two reclaim paths: **Path A: Cull local Time Machine snapshots** ```bash tmutil thinlocalsnapshots / # macOS chooses which to delete # or: tmutil deletelocalsnapshots # specific snapshot ``` 42 snapshots can easily hold 50+ GB. macOS auto-purges these under pressure, but the user perceives "disk full" before the purge fires. **Path B: Clear user caches** ```bash rm -rf ~/Library/Caches/com.docker.docker # Docker rm -rf ~/Library/Caches/com.spotify.client # Spotify brew cleanup -s # Homebrew docker system prune -af --volumes # Docker images + volumes ``` After either path, re-run `storage-pressure.sh`. Container Free Space and df should converge. ### Why "About This Mac → Storage" lies That UI counts purgeable space as "Other" and rounds. APFS snapshots are user-deletable in principle but macOS won't expose them through the UI. `tmutil` and `diskutil apfs list` are the truth. --- ## General pattern: walking the ladder For any "my Mac is doing X weird" complaint: ```bash # 1. Start with the orchestrator scripts/health-audit.sh # 2. The verdict block's "Next:" line points at the right drilldown. # Run that. If multiple rungs failed, address rung 2-3 (storage, # panics) BEFORE rung 6-7 (resource, TCC) since they're root-cause. # 3. Apply the minimum reversible fix. # Disable startup items via safe-disable-startup.sh, not by deleting plists. # Reset TCC grants via tccutil, not by editing TCC.db. # Cull snapshots via tmutil, not by APFS snapshot deletion. # 4. Re-run health-audit. Confirm the verdict cleaned up. ``` The discipline: **verify before treating**. The data is always sitting in `log show`, `tmutil`, `tccutil`, `pmset -g log`. mac-ops just asks for it correctly. ## Cross-references - The main skill flow: `SKILL.md` - For mac-ops vs windows-ops decisions: `mac-vs-windows-ops.md` - For each script's standalone use: that script's `--help`