Advisor

---
name: advisor
version: 1.0.0
description: |
  Proactive "make the most of the brain" coaching. Runs the `advisor` tool on
  a cadence and pings the user with the top high-leverage actions for their
  brain: version drift, pending migrations, stalled jobs, low embed coverage,
  setup smells, and skillpack drift. Read-only; always asks before fixing.
triggers:
  - "what should I do to get more out of the brain"
  - "is my brain set up right"
  - "brain advisor"
  - "advise me on my brain"
  - "weekly brain checkup"
tools:
  - advisor
mutating: false
---

# Brain Advisor

> **Convention:** See `conventions/brain-first.md` (via `get_skill
> conventions/brain-first`). This skill is the proactive voice of the brain —
> it tells the owner how to run it better.

## Contract

This skill guarantees:
- **Read-only.** The `advisor` tool never mutates. It computes a ranked list of
  actions from existing brain state.
- **Print, never execute.** You SHOW the user the findings and ASK before running
  any fix. The user owns every decision.
- **Bounded nagging.** On a cadence, surface only what changed or what's
  critical; don't repeat an ignored low-severity item every run.

## When to run

- On demand when the user asks "how do I get more out of this brain?"
- On a **weekly** cadence via the scheduled-checkup recipe below (even idle
  brains get a "here's how to run this better" ping).

## How to run it

Call the `advisor` tool (from the shell: `memrain call advisor '{}'`).

The payload is `{ version, generated_at, worst, findings: [...] }`, with
`worst` as the severity gate: clean, warn, or critical. Each finding has:

- `severity` — `critical` | `warn` | `info`
- `title` — one-line why-it-matters
- `fix` — the exact action to fix it (a `memrain` shell command or an MCP
  tool call, stated explicitly)

## What to do with the findings

1. Read the findings, highest severity first.
2. Summarize the top 1-3 to the user in their own channel/voice. Lead with any
   `critical` item (e.g. pending migrations).
3. For each, show the suggested `fix` and **ask** whether to run it.
4. If they say yes, run exactly the stated fix yourself — a `memrain` command
   on the host or the named MCP tool call — nothing more. Version-drift
   findings route to `skills/brain-upgrade` (the deploy loop), not to an
   ad-hoc command.
5. Never run a fix the user didn't approve.

## Scheduled checkup recipe (weekly)

Install a weekly checkup via the operator's host scheduler (a systemd timer)
or the agent harness's own scheduler — see `skills/cron-scheduler` for the
recipe. Keep the prompt THIN — the job just reads this skill and runs the
advisor:

- **Schedule:** weekly, one quiet-hours-respecting slot (e.g. Monday 09:00 local).
- **Job prompt:** `Read skills/advisor/SKILL.md and call the advisor tool. If anything is critical or new since last run, ping me with the top items and the exact fix commands. Ask before fixing.`
- **Idempotent:** the advisor is read-only, so a double-fire is harmless.

Keep a run-history page in the brain (`page_append reports/advisor-history`)
so on each fire you can tell the user what is **new since last run** rather
than re-listing everything.

## Output Format

When you surface advisor findings to the user, lead with severity and keep it
scannable:

```
Brain checkup — 2 things worth your attention

CRITICAL  Schema migrations are pending.
          Fix: memrain doctor, then apply migrations   (want me to run it?)

WARN      The server is behind the latest release.
          Fix: skills/brain-upgrade (pull + rebuild on the host)
```

- One block per finding, highest severity first.
- Always show the exact `fix` action and ASK before running it.
- If nothing is pressing, say so in one line ("brain looks healthy") — don't
  manufacture work.

## Anti-Patterns

- **Running a fix without asking.** The advisor is read-only by contract. Never
  run any `fix` action without the user's explicit yes.
- **Dumping the raw JSON at the user.** Translate findings into their voice; lead
  with what matters.
- **Re-nagging ignored low-severity items every run.** Use the "new since last
  run" delta (the `reports/advisor-history` page); respect the user's prior
  non-action.
- **Treating `info` like `critical`.** Only block/insist on `critical` findings
  (pending migrations). `info` is a gentle nudge.
- **Expecting the `advisor` tool to report workspace install state.** Over MCP
  the advisor returns brain-state signals only; whether this workspace has the
  brain's skills installed is checked via `list_brain_skillpack` (or
  `memrain skillpack` on the host).