/maintain

name: maintain
version: 1.1.0
upstream: maintain@fc834ee
description: |
  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.
triggers:
  - "brain health"
  - "check backlinks"
  - "maintenance"
  - "orphan pages"
  - "stale pages"
  - "extract links"
  - "build link graph"
  - "populate timeline"
  - "populate links"
  - "backfill graph"
  - "extract timeline entries"
  - "retriage the backlog"
  - "re-score the triage"
  - "run dream"
  - "process today's session"
  - "process yesterday's transcripts"
  - "synthesize my conversations"
  - "what patterns did you see"
  - "did the dream cycle run"
  - "consolidate yesterday's conversations"
tools:
  - get_health
  - get_page
  - put_page
  - list_pages
  - get_backlinks
  - add_link
  - search
mutating: true

Maintain Skill

Periodic brain health checks and cleanup.

Contract

This skill guarantees:

• All health dimensions are checked (stale, orphan, dead links, cross-refs, backlinks, citations, filing, tags)
• Each issue found has a specific fix action
• Back-link iron law is enforced
• Citation format is validated against the standard
• Results are reported with counts per dimension

Phases

Autonomous path (v0.36.4.0) — when you want to reach a target score

If the user asks "get my brain to 90/100" or "fix what's broken", prefer the one-command loop over walking each dimension by hand:

gbrain doctor --remediation-plan --json              # preview what would run
gbrain doctor --remediate --yes --target-score 90 --max-usd 5

`--remediation-plan` prints a dependency-ordered list (sync before extract, embed after consolidate, etc.) with per-step `est_seconds` and `est_usd_cost`. `--remediate` walks the plan, submitting each step as a Minion job, re-checking score between every step. `--max-usd N` is a hard cost cap — submission refuses when the plan would exceed the cap (prevents synthesize loops from burning Anthropic credits unattended).

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), the command bails with a list of what's missing rather than looping.

Use the per-dimension walk below (Phase 2 onward) when:

• The user explicitly asks for a dimension-by-dimension audit
• You're investigating why score is stuck below `--remediate`'s ceiling
• A specific dimension needs manual judgment that the auto path skips

Manual path

1. **Run health check.** Check gbrain health to get the dashboard. 2. **Check each dimension:**

Stale pages

Pages where compiled_truth is older than the latest timeline entry. The assessment hasn't been updated to reflect recent evidence.

• Check the health output for stale page count
• For each stale page: read the page from gbrain, review timeline, determine if compiled_truth needs rewriting

Orphan pages

Pages with zero inbound links. Nobody references them.

• Review orphans: are they genuinely isolated or just missing links?
• Add links in gbrain from related pages or flag for deletion

Dead links

Links pointing to pages that don't exist.

• Remove dead links in gbrain

Missing cross-references

Pages that mention entity names but don't have formal links.

• Read compiled_truth from gbrain, extract entity mentions, create links in gbrain

Link graph extraction

If link_count is 0 or low relative to page_count, run batch extraction:

gbrain extract links --dir ~/brain

This scans all markdown files for entity references, See Also sections, and frontmatter fields, then creates typed links in the database.

Timeline extraction

If timeline_entry_count is 0, extract structured timeline from markdown:

gbrain extract timeline --dir ~/brain

Dream cycle (v0.23): synthesize + patterns

`gbrain 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 -> orphans

The two new phases consolidate yesterday's conversations into long-term memory:

**Synthesize phase (two-stage cascade):** reads transcripts from `dream.synthesize.session_corpus_dir`, 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 t