health-check

Health Check

Report-first resource triage. Answers two questions: can we start <target> right now, and what is the safest way to recoup headroom if not. Destructive reclaim is never automatic — only the regenerable build cache is pruned without asking.

This skill spans two scopes, and step 0 decides which one you are in. Docker inventory and every reclaim lever live on the machine running the daemon; memory, swap, disk and CPU can be read on either side but mean different things depending on where you read them. The sandbox has had no host Docker socket since #756 removed it as a host-root escape path, so a sandboxed invocation reports container-scope metrics and hands the Docker half to the orchestrator. Never present container figures as host figures — that is the failure mode this structure exists to prevent, and it is worse than reporting nothing, because a green container disk row reads like permission to start a multi-GB image build.

target is free text naming what you intend to start (a compose path, make dev, a service name). It sizes the verdict — a full docker compose build and a make dev against already-running services have very different footprints, so always pin down which before judging "sufficient."

Performance rules

Default to a fast path: one scope classification, one host snapshot, one Docker summary, one running-container list, and one exited-container list. Do not run verbose or per-container probes until the summary shows a likely binding constraint or the user asks for reclaim candidates.

• Gate expensive commands: docker system df -v, docker stats, docker exec <container> ps ..., du, and nested-Docker inspection are second-pass diagnostics, not baseline checks.
• Run expensive diagnostics once and reuse the captured output. Never call docker system df -v inside a loop over volumes/images/containers.
• Prefer scoped reads over broad scans: explicit cache paths (~/.npm, project .pnpm-store) are acceptable; du -sh /home/* or filesystem-wide find is not.
• Keep reruns delta-oriented: if a prior health-check in the same thread already found the shape of the problem, recheck only the changed metrics unless the target changed.
• Never retry a Docker call that failed for want of a daemon. Step 0 settles reachability once. Nine copies of the same connection error is not diagnosis.