maintain

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

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

<!-- QMD: graph extraction (gbrain extract) not yet available -->

Back-link enforcement

Check that the back-linking iron law is being followed:

• For each recently updated page, check if entities mentioned in it have corresponding back-links FROM those entity pages
• A mention without a back-link is a broken brain
• Fix: add the missing back-link to the entity's Timeline or See Also section
• Format: - **YYYY-MM-DD** | Referenced in [page title](path) -- brief context

Filing rule violations

Check for common misfiling patterns (see skills/_brain-filing-rules.md):

• Content with clear primary subjects filed in sources/ instead of the appropriate directory (people/, companies/, concepts/, etc.)
• Use gbrain search to find pages in sources/ that reference specific people, companies, or concepts -- these may be misfiled
• Flag misfiled pages for review or re-filing

Citation audit

Spot-check pages for missing [Source: ...] citations:

• Read 5-10 recently updated pages
• Check that compiled truth (above the line) has inline citations
• Check that timeline entries have source attribution
• Flag pages where facts appear without provenance

Tag consistency

Inconsistent tagging (e.g., "vc" vs "venture-capital", "ai" vs "artificial-intelligence").

• Standardize to the most common variant using gbrain tag operations

Embedding freshness

Chunks without embeddings, or chunks that haven't been re-indexed after content changes.

• Run gbrain embed to trigger QMD re-indexing (update + embed) for all content files.
• For large brains, use gbrain reindex which triggers full QMD update + embed.

SQLite health

Run gbrain doctor --json and check SQLite status.

• Integrity check: doctor verifies SQLite integrity via PRAGMA integrity_check.
• Database size: large databases may need VACUUM to reclaim space after deletions.
• To VACUUM: stop gbrain, then run sqlite3 ~/.gbrain/data/brain.db "VACUUM;" manually.

Schema health

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.

Open threads

Timeline items older than 30 days with unresolved action items.

• Flag for review

<!-- QMD: Autopilot/Minions not available -- future lightweight alternative planned --> <!-- QMD: RLS verification is Postgres-only, not applicable --> <!-- QMD: File storage health is cloud-only, not applicable -->

Report Storage

After maintenance runs, save a report:

• Health check results (before/after scores for each dimension)
• Back-link violations found and fixed
• Filing rule violations found
• Citation gaps flagged
• Outstanding issues requiring user attention

This creates an audit trail for brain health over time.

Quality Rules

• Never delete pages without confirmation
• Log all changes via timeline entries
• Check gbrain health before and after to show improvement

Anti-Patterns

• Fixing pages without reading them first -- you must understand context before editing
• Silently skipping dimensions -- every dimension must be checked and reported, even if clean
• Deleting orphan pages without checking if they should be linked instead
• Running embedding refresh during peak usage hours
• Batch-fixing back-links without verifying the relationship is real
• Marking a dimension "clean" without actually querying it
• Rewriting compiled truth without reading the full timeline first
• Removing tags without checking if other pages use the same tag consistently

Output Format

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         |
| Schema health        | N           | N     | N         |
| Open threads         | N           | N     | N         |

### Details
[Per-dimension breakdown with specific pages and actions taken]

### Outstanding Issues
[Items requiring user attention or confirmation]

Heartbeat Integration

For production agents running on a schedule, integrate gbrain health checks into your operational heartbeat.

On every heartbeat (hourly or per-session)

Run gbrain doctor --json and check for degradation. Report any failing checks to the user. Key signals: SQLite health, QMD index status, embedding coverage, schema version.

Weekly maintenance

Run gbrain embed to refresh embeddings for pages that have changed since their last indexing. QMD handles embedding locally via the Qwen3-Embedding-0.6B model.

Daily verification

Verify sync is running: check gbrain stats and confirm last_sync is within the last 24 hours. getStats() returns last_sync_at (ISO timestamp of last successful sync). If null or older than 24h, the brain may be drifting from the repo.

Stale compiled truth detection

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).

Tools Used

• Check gbrain health (get_health)
• List pages in gbrain with filters (list_pages)
• Read a page from gbrain (get_page)
• Write a page in gbrain (put_page)
• Check backlinks in gbrain (get_backlinks)
• Link entities in gbrain (add_link)
• Search gbrain (search)