# 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 <name>   # 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`
