gbrain-advisor

# gbrain Advisor > **Convention:** See `skills/conventions/brain-first.md`. This skill is the > proactive voice of the brain — it tells the owner how to run it better. ## Contract This skill guarantees: - **Read-only.** `gbrain advisor` 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 cron recipe below (even idle brains get a "here's how to run this better" ping). - Monthly, the advisor also surfaces the backup-coverage verdict (`gbrain backup status` — which knowledge repos have no git remote); relay any warn. ## How to run it ```bash gbrain advisor --json ``` Exit code is the severity gate (E2): `0` clean, `1` warn, `2` critical. The JSON payload is `{ version, generated_at, worst, findings: [...] }`. Each finding has: - `severity` — `critical` | `warn` | `info` - `title` — one-line why-it-matters - `fix.command_argv` — the exact command to fix it (a structured argv) - `fix.dispatch_id` — present when the fix is safe to run via `--apply` ## 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 `fix.command_argv` and **ask** whether to run it. 4. If they say yes and the finding has a `fix.dispatch_id`, you may run it locally with an explicit confirm: ```bash gbrain advisor --apply <dispatch_id> ``` `--apply` is local-only, runs the fix as a structured argv (no shell), and confirms first. Findings without a `dispatch_id` are not auto-runnable — run their `fix.command_argv` yourself after the user agrees. 5. Never run a fix the user didn't approve. ## Cron recipe (weekly checkup) Install a weekly job via the `cron-scheduler` skill. 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/gbrain-advisor/SKILL.md and run gbrain advisor --json. 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. The advisor records a local run 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: ``` 🧠 gbrain checkup — 2 things worth your attention CRITICAL Schema migrations are pending. Fix: gbrain apply-migrations --yes (want me to run it?) WARN gbrain 0.44 is available (you're on 0.43). Fix: gbrain upgrade ``` - One block per finding, highest severity first. - Always show the exact `fix` command and ASK before running it. - If nothing is pressing, say so in one line ("brain looks healthy") — don't manufacture work. ## When it fails Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill: - A `critical` finding (pending migrations) carries a fix such as `gbrain apply-migrations --yes`: ask the user before running it; findings without a `dispatch_id` are not auto-runnable. - `gbrain advisor` cannot reach the brain (`GBRAIN_DB_ACCESS` marker): route to the db-repair skill instead of reporting "no findings". ## Anti-Patterns - **Running a fix without asking.** The advisor is read-only by contract. Never run `--apply` (or any `fix` command) 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; respect the user's prior non-action. - **Treating `info` like `critical`.** Only block/insist on `critical` findings (pending migrations). `info` is a gentle nudge. - **Calling the MCP `advisor` op for workspace install state.** Over MCP the advisor returns brain-state signals only; uninstalled-skill findings are a local-CLI concern.