macos-watchdog
Installation
SKILL.md
macOS Watchdog
A watchdog is a launchd job that periodically detects a recurring problem and remediates it without a human. The craft is not "how to install a plist" — it is how to keep the watchdog from becoming a new disturbance: every watchdog on this machine was born from an incident, and the recurring failure mode afterward is the watchdog itself (false "all good" reports, notification floods, re-launching apps the user quit, fork-bomb replays).
The governing principle, learned the expensive way: a watchdog's lifecycle is bound to its premise state. When the condition it exists to fix cannot be fixed by it (broken WiFi, user quit the target app, prerequisite state gone), the watchdog must stand down by itself — not wait for a human to disable it.
Entry decision tree
| The situation is… | Go to |
|---|---|
| Installing a NEW watchdog from scratch | § Deploy, then § The quiet-watchdog contract |
| An existing watchdog misbehaves (spam, re-launches apps, hammers) | § The quiet-watchdog contract, diagnose which clause it violates |
| Stopping / disabling / restarting a job | § Stop semantics |
| plist key details (KeepAlive forms, domains, logging, resource limits) | references/launchd-plist-reference.md |
| Checking whether a plist edit is active, or comparing job argv / explicit ENV / configured paths | Run scripts/inspect_native_job.py with the exact expected plist; read references/native-job-readback.md for result and source-selection rules |
| Cooldown/backoff/notification-throttle patterns + sanitized war stories | references/quiet-watchdog-patterns.md |
| SRE alert layering (page vs ticket, fatigue numbers) | references/alert-discipline.md |
| A watchdog alert appears under Script Editor or its sender is unclear | references/alert-discipline.md § Message content; inspect the delivered card |