/health — the five-minute project checkup

Answers one question: is this project's acstack setup sound, or quietly rotting? Named /health, not /doctor — Claude Code ships a built-in /doctor for its own install, and this skill examines your project, not your tooling (naming verdict 2026-07-27).

Adjacent skills: /audit docs (deep doc-vs-reality drift triples; /health is the quick structural checkup) · /resume (where the work is; /health is whether the setup is broken) · /triage (grooms the backlog; /health checks the scaffolding around it).

Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:

link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)"   # empty = not symlinked
pack="$(dirname "$(dirname "$link")")"   # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
  "$pack/bin/acstack-config" || true          # resolved keys, with sources
  "$pack/bin/acstack-update-check" || true    # ≤1 fetch/day; silent ONLY if already checked today
  "$pack/bin/acstack-recall" || true          # LEARNINGS.md + bug-class names, capped 3KB
else
  echo "runtime off — proceeding without recall/update-check"
fi

Operating principles

• Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
• Never delete a decision. Supersede it: ~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason.
• Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
• Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
• Attribution: follow the project's attribution setting (default none) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit -m/-F messages only.
• Config: read .claude/acstack.md at the project root (fall back to ~/.claude/acstack.md) before acting. ## Settings keys override pack defaults; a ## <skill-name> section overrides both. Unknown keys and sections are ignored.
• Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
• Recall: if LEARNINGS.md exists at the project root, read it before starting.
• Conduct: follow the acstack-conduct block in this repo's AGENTS.md — the word is the mode; the user sets the pace.
• Hackathon lane: if the project's AGENTS.md carries the acstack:hackathon-lane block, only /do changes the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route.

One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name its path in the report's scope line. If more than one candidate set exists — a monorepo, nested products, an apps/* tree each with its own docs — list the candidates and STOP. Never pick one silently: a confident answer about the wrong product is worse than no answer (conduct rule 8).

Stance

Read-only, always. Every ✗ finding names the exact command or edit that would fix it — and applies none of them. /health diagnoses; the user (or /plan, /learn, /journal on request) treats. (Residual: the git log grant accepts --output=FILE; a prefix grant can't forbid it, so "read-only" is in use, not mechanically absolute — recorded in check.sh §13.)

The checks

Exact commands for each live in references/health-checks.md. Run all that apply; skip none silently — a check that can't run (e.g. copy install instead of symlinks) is reported as skipped — <why>.

1. Docs. BRIEF/PLAN/JOURNAL present (legacy names accepted and named as such). JOURNAL stale if this branch's own commits postdate its last entry — reachable from HEAD but not from the default branch, never the whole log. Commits on the default since the last journal commit are a separate info line (<default> has N commits since the last entry — other sessions' integrated work), not this branch's staleness; on the default itself the two coincide and stale means stale. With N sessions a whole-log rule fires forever and stops being read — measured 2026-09-16 on the pack's own repo: 4 "unjournaled" commits on a branch with 0 of its own (5.17.4). PLAN has an open phase with a runnable exit criterion.
2. Pointer. CLAUDE.md is exactly the one-line @AGENTS.md pointer. Anything else is flagged — never silently rewritten (/plan's rule).
3. Conduct. The marker-fenced acstack-conduct block exists in AGENTS.md and matches the installed pack's CONDUCT.md block. Stale → show the refresh edit. Referrals. The acstack-referrals block exists too and matches the pack's. It rosters the skills an agent cannot see (disable-model-invocation: true), so its absence costs the user every typed-only skill silently — fix is /plan seed, idempotent. One product per repo. More than one document set below the root, or a workspace marker, is reported as info — unsupported, not broken — naming every set found. The pack models one product per repository; with two, a document-reading skill would report on the wrong one with full confidence.
4. Config. .claude/acstack.md readable; keys outside the README table listed as info (the extension hook, not an error); mode prerequisites consistent — tracking: tickets with no gh, no auth, or no remote is a ✗.
5. Secrets. No .env-class file tracked; no gitignore negation un-ignoring one; no obvious key patterns in tracked files; .env absent from history (in history → the key is burned; say "rotate").
6. Attribution. Recent commit messages honor the attribution config — default none means any AI trailer or tool mention is a ✗.
7. Learnings. LEARNINGS.md present and touched within stale-days (default 30, ## triage section) — otherwise an info line pointing at /learn. A project that stops learning is drifting; this is info, not failure.
8. Tickets extras (tracking: tickets only). gh installed and authenticated, the pack label set present, the issue template present, stale-issue count vs stale-days (count only — the sweep itself is /triage's job).
9. Agent instructions. The project's own rules in AGENTS.md (outside the acstack-conduct block) don't contradict a conduct rule and cite no dead paths or skills. A contradiction is a ✗ that names both rules; judgment-led, see references/health-checks.md §9.
10. Irreversible-act deny set. How many entries of the set below are present in ~/.claude/settings.json, or in the project's .claude/settings.json — reported as <n> of 5 present, naming the absent ones, with the fix being "paste the missing entries" and never applied. This row is info: it carries no ✓ or ✗ and never counts toward the issue total, because the set is a denylist that sh -c and script files defeat outright, so a pass here would certify a safety property it cannot deliver. README's "Irreversible acts" section carries the three measured limits. The set is canonical there and byte-identical here:

{
  "permissions": {
    "deny": [
      "Bash(gh repo delete:*)",
      "Bash(git push --force:*)",
      "Bash(git push -f:*)",
      "Bash(rm -rf:*)",
      "Bash(npx prisma migrate reset:*)"
    ]
  }
}

Checks that depend on machinery from later wave-4.5 items — a session hook (4.4), the conduct block mirrored into ~/.claude/CLAUDE.md (4.4), and update-stamp/telemetry freshness (4.3) — are deferred to those items and not reported as missing until they land.

Report shape

First line is the verdict: HEALTHY or <N> issues, <M> info. Then the table — check | ✓ / ✗ / info / skipped | evidence | fix command — one row per check above, in order. Close with scope — this line first, one source line, the same in every branch-reading skill of this pack, because the verdict is about one branch's tree (5.17.4):

Scope: branch <branch> @ <sha> vs <default> @ <sha> — a verdict about this branch's tree, not the project's; the merged tree is the integrator's to re-check.

Then what was checked, what was skipped and why. No prose padding between the verdict and the table; the table is the report.