Brain health checks: back-link enforcement, citation audit, filing validation, stale info detection, orphan pages, and benchmarks. Use when asked to check brain health, run maintenance, or audit quality.
71%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./skills/maintain/SKILL.mdPeriodic brain health checks and cleanup.
This skill guarantees:
Routine maintenance, startup checks, doctor --fix, and a request to "fix what's
broken" do not authorize writer topology changes. On owner_unavailable or a
writer coordination refusal, inspect gbrain sources writer status --brain <id> --json on the selected host first and report the owner, epoch, enabled state and
blocked recovery to the operator. Do not claim a checkout, activate managed mode,
transfer an owner, replace identities, or remove ownership markers as a repair.
When the status reads enabled: false and the refusal says unbound_source,
the brain is in classic mode on purpose: report that writes go through the
checkout (file, commit, gbrain sync) and leave it classic.
Deliberate administration requires a separately approved topology change and the
action-specific intent plus reviewed state precondition described in
docs/architecture/topologies.md. Neither a TTY nor --yes nor
--confirm-quiesced substitutes for that decision. Remote credentials remain
ineligible for local writer administration.
If the user asks "get my brain to 90/100" or "fix what's broken", preview first and ask before applying anything:
gbrain doctor --remediation-plan --json # preview: job steps + repair steps
# Show the user the repair steps (each "requires user agreement") and the cost.
# Only after the user agrees (plan_hash from the preview binds the approval):
gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --target-score 90 --max-usd 5--remediation-plan prints a dependency-ordered list of job steps (sync before
extract, embed after consolidate, etc.) with per-step est_seconds and
est_usd_cost, and, independent of the score target, the PROTECTED repair steps
for every gbrain repair kind with pending items. Each step carries the exact
command that applies it, and the plan ends with one combined command.
--remediate runs the repair steps only with --include-repairs (the user's
agreement; without it they are listed as skipped), then walks the job plan,
submitting each step as a Minion job and re-checking score between steps.
--max-usd N is a cumulative cost cap across the run and every --resume: a
paid step that would exceed it is not started, free steps still run, and the run
stops with a resume command that keeps the cap and the agreement.
When the target score is unreachable for the brain (empty brain with no entity
pages → graph_coverage caps at 70; unconfigured embedding key → caps at 60),
job steps stop with a list of what's missing rather than looping; included repair
steps still run. --json classifies each finding cleared, pending,
consent_required, operator_required (follow its instruction) or
unsupported (report it; nothing clears it yet). After an upgrade, follow the
recipe in docs/guides/repair.md#recover-after-upgrading-to-this-release.
Use the per-dimension walk below (Phase 2 onward) when:
--remediate's ceilingget_health) to get the dashboard. get_health needs admin scope; without it, call get_brain_health (read scope), which returns bands only (write capacity, write failures, ghost pages, unsearchable chunks), and skip the dimensions it cannot answer: stale pages, orphan pages, dead links, embed coverage, link and timeline counts and the brain score. Name the skipped dimensions in the report and ask for an admin token, or for gbrain doctor --json on the brain host, to cover them.Pages where compiled_truth is older than the latest timeline entry. The assessment hasn't been updated to reflect recent evidence.
Pages with zero inbound links. Nobody references them.
Links pointing to pages that don't exist.
Pages that mention entity names but don't have formal links.
If link_count is 0 or low relative to page_count, run batch extraction:
gbrain extract links --dir ~/brainThis scans all markdown files for entity references, See Also sections, and frontmatter fields, then creates typed links in the database.
If timeline_entry_count is 0, extract structured timeline from markdown:
gbrain extract timeline --dir ~/braingbrain dream runs the full maintenance cycle (core phases shown; opt-in
phases like atoms/concepts/drift slot in between):
lint -> backlinks -> sync -> synthesize -> extract -> patterns -> embed -> orphansfence_repair runs right after sync, once per maintenance pass: it repairs
the facts and takes fences sync held or pages store malformed (the same plan
gbrain repair fences previews), for at most 300 s or a third of the job's
remaining time, and resumes on the next run. content_repair runs right after
it (#6377): the rest of the content-repair lane, today the slug-conflicts
kind that removes a stray frontmatter slug: or records a recommended merge
for a person (gbrain repair content previews both kinds), for at most 120 s
or a third of the remaining time. Pause both with
gbrain config set fences.repair.enabled false.
The two new phases consolidate yesterday's conversations into long-term memory:
Synthesize phase (two-stage cascade): reads the cycle source's transcripts from
dream.synthesize.session_corpus_dir (another source's sessions wait for their own
gbrain dream --source <id> --phase synthesize; unresolved or legacy files are held,
already-extracted ones included, until gbrain sweep --assign-corpus <source>), then triages before it spends: a cheap
utility-tier judge (models.dream.triage) scores every new file 0–1 for
salience and pre-extracts candidate quotes + entities, cached in
dream_verdicts with the judging model + prompt version (bounded per cycle
by dream.triage.max_ms, default 5 min — deferred files retry next cycle,
never silently rejected). A file passes the gate two ways: it scores at or
above dream.triage.threshold (default 0.5), OR the verified-segment
rescue fires — a score in [dream.triage.rescue_floor, threshold) still
passes when at least dream.triage.rescue_min_segments (default 2; 0
disables) of the judge's own quoted segments verify as substrings of the
transcript AND the content type is in dream.triage.rescue_content_types
(default mixed,reflection,idea,strategy,people — never routine/technical).
The rescue costs nothing (no extra LLM calls, it re-reads the cached verdict)
and it is what recovers real signal buried in an otherwise mundane transcript.
The whole gate is applied at READ time, so retuning the threshold or the
rescue knobs re-gates with zero new LLM calls. Files that pass fan out one
synthesis subagent per transcript chunk, each primed with the triage map. By default
each child runs in oneshot mode (dream.synthesize.mode, default oneshot):
ONE tool-less completion against a prompt carrying a pre-retrieved LINK
CANDIDATES manifest (dream.synthesize.link_manifest, default on) and the
write allow-list, validated end-to-end (slug fences, task shapes, wikilinks)
before any page is written programmatically. A response that fails validation
falls back to the classic agentic loop in the same job, where the
dream.synthesize.max_turns cap (default 16) applies; revert dial:
gbrain config set dream.synthesize.mode agentic. Each child writes reflections
(wiki/personal/reflections/...) and originals (wiki/originals/ideas/...);
people timeline entries are written only on the agentic path (fallback or
mode agentic), where the child has the add_timeline_entry tool. The orchestrator collects the slugs from
subagent_tool_executions (NOT pages.updated_at — that would pick up
unrelated writes), runs the quote verify pass over them (below), and
reverse-renders each new page from DB → markdown on disk. To re-apply the
gate after retuning the threshold or the rescue knobs, or to drain a queued
backlog, run gbrain dream retriage --dry-run (zero LLM calls, cached
scores only) then gbrain dream retriage --reconcile-queue; --force
re-judges everything from scratch. Retriage reads the SAME gate the cycle
does, so a reconcile sweep never cancels a job the rescue admitted.
Claim verification (post-write, zero LLM): after slug collection and
before the reverse-write, dream.synthesize.quote_verify (default on) checks
every page this phase's children wrote against the transcripts that produced
it. Pages created this run are checked whole; pages that already existed are
checked only on the sentences this run added. An exact quote is kept; a quote
that differs only in whitespace, curly quotes, dashes, or case, or a close
paraphrase inside one speaker's turn, is replaced with the verbatim transcript
slice. A sentence is quarantined when a quote grounds nowhere or only across
two speakers, when it attributes a real quote to the wrong speaker, or when it
states a number or date the transcript lacks. Quarantined sentences leave the
page body (and the timeline, facts and links derived from it) and are kept
verbatim in frontmatter unverified_claims, which get_page shows but search,
recall and think do not read. Grounded quotes record their source span and
speaker in grounding.quotes. Nothing is ever fabricated. Telemetry lands in
details.synthesis.quote_verify; the config key is the incident off switch.
Patterns phase: runs after extract (so the graph state is fresh).
Reads recent reflections within dream.patterns.lookback_days (default 30),
runs a single Sonnet pass to surface recurring themes, and writes pattern
pages to wiki/personal/patterns/<theme> when ≥dream.patterns.min_evidence
(default 3) reflections support a pattern. A completed run records the newest
reflection it consumed (dream.patterns.last_evidence_ts); until a reflection
in the window is newer than that, re-runs skip with no_new_evidence instead
of paying for another model pass — gbrain dream --phase patterns --once
forces one.
Quality bar (Iron Law for synthesis):
Trust boundary (allowed_slug_prefixes): the synthesis subagent runs with an
explicit allow-list of write paths sourced from _brain-filing-rules.json's
dream_synthesize_paths.globs. Even on prompt-injection success, the subagent
cannot write outside that list. Trust comes from PROTECTED_JOB_NAMES — MCP
cannot submit subagent jobs at all. Editing the JSON is the only way to add
a new directory the synthesizer can write to.
Idempotency + privacy: transcripts are keyed by (file_path, content_hash),
so re-running on the same content is a no-op. dream.synthesize.exclude_patterns
(default ["medical", "therapy"]) filters out transcripts before any LLM call.
Each entry is auto-wrapped as a word-boundary regex (e.g. medical matches
"medical advice" but NOT "comedical"). Power users may pass full regex.
Cooldown: dream.synthesize.cooldown_hours (default 12) skips synthesize
for that long after a fully drained pass. The completion timestamp is stored
in dream.synthesize.last_completion_ts and is written only when every child
completed and nothing was deferred (synthesis budget, triage time budget or
publish pending), never on skipped or failed runs. So under a standing
backlog the cooldown never applies and synthesize runs every cycle until the
backlog drains (#6753); it is not a cap of ~2 runs a day. The same setting
also holds a growing transcript: one whose earlier version was synthesized
within dream.synthesize.cooldown_hours is skipped as resynthesis_cooldown
until that window passes, so it is re-synthesized at most about twice a day.
To cap spend, use
dream.synthesize.max_submissions_per_source_per_day. Explicit --input /
--date / --from / --to invocations bypass cooldown and the hold.
--dry-run semantics: runs the scored triage pass (judges + caches
verdicts for new files) but skips the synthesis subagents. NOT zero LLM
calls — for a zero-call preview from cached scores use
gbrain dream retriage --dry-run instead.
Configure synthesize on a fresh brain:
gbrain config set dream.synthesize.session_corpus_dir /path/to/transcripts
gbrain config set dream.synthesize.enabled true
gbrain dream --phase synthesize --dry-run --json # preview
gbrain dream # full cycleInvocation patterns:
gbrain dream # full cycle
gbrain dream --phase synthesize # just synthesize
gbrain dream --phase patterns # just patterns
gbrain dream --input ~/transcripts/2026-04-25.txt # ad-hoc one transcript
gbrain dream --from 2026-04-01 --to 2026-04-25 # backfill range
gbrain dream --json # CycleReport JSONAuto-commit deferred to v1.1: v1 writes files to brain_dir but does NOT
git add / commit / push. Either commit yourself or let gbrain autopilot
handle it.
Parses - **YYYY-MM-DD** | Source — Summary and ### YYYY-MM-DD — Title formats.
The Source — Summary dash may be an em dash, an en dash or a spaced hyphen (-);
a colon (Source: Summary) is prose, so the row keeps source: markdown and the
whole text as its summary.
Note: extracted entries improve structured queries (gbrain timeline), not vector search.
gbrain maintain --status shows the last free-upkeep run, which an open
gbrain serve does while idle; an item serve could not finish in 30 slices is
listed as parked, and gbrain maintain --unattended finishes it. For a brain
no agent opens most days, offer gbrain maintain --schedule (asks consent). On a Postgres brain with a repo,
verify autopilot:
gbrain autopilot --statusThe exit code is trustworthy for gating: 0 fresh (or nothing installed),
1 needs attention (stale heartbeat, never ran, or paused by a migration),
2 the daemon disabled itself (its repo path vanished). --json emits the
full report (state, heartbeat_age_seconds, paused_reason,
disabled_reason). Status reads only the filesystem, so it works even
when the database is down.
If not running, install it:
gbrain autopilot --install --repo ~/brainAutopilot runs sync, extract, and embed in a continuous loop with adaptive scheduling.
In v0.11.1+, autopilot dispatches each cycle as a single autopilot-cycle
Minion job and supervises the worker child — one install step gives you
sync + extract + embed + backlinks + durable job processing.
A v0.11.0 install where the migration skill never fired leaves Minions
partially set up: schema is applied, but ~/.gbrain/preferences.json
doesn't exist, autopilot runs inline, host manifests still reference
agentTurn. Repair:
# Check migration status
gbrain apply-migrations --list
# Apply pending migrations (idempotent; safe on healthy installs)
gbrain apply-migrations --yes
# If host-specific handlers are flagged in ~/.gbrain/migrations/pending-host-work.jsonl:
# walk them per skills/migrations/v0.11.0.md + docs/guides/plugin-handlers.md,
# ship handler registrations in the host repo, then re-run apply-migrations.Full troubleshooting guide: docs/guides/minions-fix.md.
Check that the back-linking iron law is being followed:
- **YYYY-MM-DD** | Referenced in [page title](path) -- brief contextCheck for common misfiling patterns (see skills/_brain-filing-rules.md):
sources/ instead of the
appropriate directory (people/, companies/, concepts/, etc.)sources/ that reference specific
people, companies, or concepts -- these may be misfiledSpot-check pages for missing [Source: ...] citations:
Inconsistent tagging (e.g., "vc" vs "venture-capital", "ai" vs "artificial-intelligence").
The links and timeline_entries tables are the structured graph layer.
Populate them periodically or after major imports:
gbrain extract links --source db — backfill structured links by walking pages
from the engine. Reads [Name](people/slug) / [Name](companies/slug) references
and infers relationship types (attended, works_at, invested_in, founded,
advises, mentions, source). Idempotent. Use --source fs --dir <brain>
if you have a markdown checkout to walk instead.gbrain extract timeline --source db — backfill structured timeline entries.
Parses - **YYYY-MM-DD** | summary lines from page content. Idempotent (DB
UNIQUE constraint).gbrain extract all --source db — both in one run.gbrain graph-query <slug> --depth 2 — verify connectivity (use any well-known
entity slug as a probe).gbrain stats — verify link_count > 0 and timeline_entry_count > 0 after extraction.gbrain health — review link_coverage and timeline_coverage percentages
on entity pages (person/company). Below 50% means more extraction is needed.
On brains with very few entity pages these report "too few to grade"
(null in JSON, with entity_page_count carrying the denominator) instead
of a misleading 0%/100% — grow the entity set before acting on coverage.Available link types (use with gbrain graph-query --type):
attended, works_at, invested_in, founded, advises, mentions, source.
Going forward, every gbrain put call auto-creates and reconciles links via the
auto-link post-hook (default on; disable: gbrain config set auto_link false).
So link-extract is mostly a one-time backfill. timeline-extract should be re-run
after bulk imports or content edits that add new dated entries.
gbrain features --json # scan for underused features + recommendationsRun weekly alongside lint. Surfaces missing embeddings, unused integrations, and configuration improvements.
Chunks without an embedding yet (--stale selects exactly those). Embedding
calls the configured provider, which bills per token, so this is paid work
that needs the user's approval first:
gbrain embed --stale --dry-run.gbrain embed --stale --yes --max-usd <cap>
with the cap they approved.Without approval the command stops with exit 3 and an [AGENT] block asking
you to ask the user; relay it and stop. Never pass --yes on your own.
For a long run (>1000 chunks), route the approved command through the
durable ladder in skills/minion-orchestrator/SKILL.md instead of a bare
background shell, which hides that exit 3 in a log file.
To see what search cannot reach on one source, run
gbrain pages unsearchable --source <id> --json (read-only). Read
semantic_unsearchable, not only unsearchable: it adds keyword_only
pages, which keyword search finds but vector search misses. awaiting_sync
counts files sync still holds, which no embedding state includes; follow
gbrain sync status --source <id> --json for those. Each row carries its fix.
Run gbrain doctor --json and check the RLS status.
All tables should show RLS enabled. If not, run gbrain init again.
Check that the schema version is up to date. gbrain doctor --json reports
the current version vs expected. If behind, gbrain init runs migrations
automatically.
Check the integrity of stored files and redirect pointers:
gbrain files verify to check all DB records have valid datagbrain files status to see migration state (local, mirrored, redirected).redirect.yaml pointers that reference missing storage filesTimeline items older than 30 days with unresolved action items.
Periodically verify search quality hasn't regressed. Run a battery of test queries across difficulty tiers:
Compare results from gbrain search (keyword) vs gbrain query (hybrid).
Quality matters more than speed (2.5s right > 200ms wrong).
When to run benchmarks:
For production agents running on a schedule, integrate gbrain health checks into your operational heartbeat.
Run gbrain doctor --alert --json. Exit 0: report nothing. Exit 17: report each
alert.items entry with its fix. Exit 18: report only when
alert.consecutive_unknown is 2 or more. Never alert on health_score.
Refresh embeddings for chunks that have none yet, with the same consent steps
as "Embedding freshness" above: gbrain embed --stale --dry-run, relay the
estimate, and after the user agrees gbrain embed --stale --yes --max-usd <cap>
(or a standing approval the user set with
consent.preapprove.paid.max_usd_per_run). For large brains (>5000 pages),
submit the approved command through the minion-orchestrator durable ladder;
if you must background it in a shell, keep the exit code:
(gbrain embed --stale --yes --max-usd <cap>; echo "exit=$?") > /tmp/gbrain-embed.log 2>&1 &
tail -2 /tmp/gbrain-embed.log # later: the last line is exit=<code>Exit 3 in that log means the run needs the user's approval: relay it and stop.
Run gbrain backup status and relay anything red. It verifies every knowledge
repo (and the agent workspace) has a git remote — local-only means a disk loss
loses it. Fixes are printed inline (gbrain bootstrap repo, git remote add,
gbrain sources harden <id>).
Verify sync is running: check gbrain stats and confirm last_sync is within
the last 24 hours. If sync has stopped, the brain is drifting from the repo.
Flag pages where compiled truth is >30 days old but the timeline has recent entries. This means new evidence exists that hasn't been synthesized. These pages need a compiled truth rewrite (see the maintain workflow above).
After maintenance runs, save a report:
This creates an audit trail for brain health over time.
Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:
gbrain doctor --remediate steps marked "requires user agreement" (PROTECTED repairs, paid steps): show the plan and cost, and run with --yes --include-repairs --expect <plan_hash> --max-usd <n> (the hash from --remediation-plan --json) only after the user agrees; preview_changed means the plan moved, so preview and ask again. A step that would exceed the cap is not started.operator_required: follow its instruction or relay it to the brain host's operator. consent_required: ask the user.writer_coordinator_required, writer_not_quiesced, recovery_required): inspect gbrain sources writer status and hand the blocked recovery to the operator; never claim a checkout or delete a lock.persistence_terminal_failures: run its fix.command (an active blocker: a recovery record or a sync checkpoint blocker; or an unresolved gbrain-defect class to report with the receipt ids). For the rest of the pile, gbrain sources writer failures <source> --group-by category (read-only) groups receipts with a fix and drill-down per group; historical rows need nothing. Never cancel or edit receipts to clear the count. Runbook: terminal write failures.gbrain dream stops on a budget (exit 11): run the printed resume_command within the agreed budget.The maintenance report follows this structure:
## Brain Health Report — YYYY-MM-DD
| Dimension | Issues Found | Fixed | Remaining |
|----------------------|-------------|-------|-----------|
| Stale pages | N | N | N |
| Orphan pages | N | N | N |
| Dead links | N | N | N |
| Missing cross-refs | N | N | N |
| Back-link violations | N | N | N |
| Citation gaps | N | N | N |
| Filing violations | N | N | N |
| Tag inconsistencies | N | N | N |
| Embedding staleness | N | N | N |
| Security (RLS) | N | N | N |
| Schema health | N | N | N |
| File storage | N | N | N |
| Open threads | N | N | N |
### Details
[Per-dimension breakdown with specific pages and actions taken]
### Benchmark Results (if run)
[Tier 1-4 query results with pass/fail]
### Outstanding Issues
[Items requiring user attention or confirmation]garrytan/gbrain
f4d1866
Also appears in
since Sep 22, 2026
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.