| name | gbrain-maintain |
| description | Comprehensive brain health maintenance: multi-dimension diagnostics, benchmark scoring, heartbeat loop, compiled-truth refresh, and Slack report output. Wraps `gbrain doctor --json`, `gbrain health` (text dashboard), `gbrain stats`, and `gbrain search` into an actionable maintenance workflow. |
| disable-model-invocation | true |
gbrain-maintain
Comprehensive brain health maintenance skill adapted from garrytan/gbrain
maintain skill (v0.10). Provides 13-dimension health checks, benchmark
scoring, heartbeat cadence, compiled-truth refresh, and Slack report output.
Prerequisites
gbrain CLI installed and authenticated (gbrain auth status)
- Brain repository configured (
gbrain config)
- Postgres/pgvector backend accessible
Modes
| Mode | Trigger | Description |
|---|
diagnose | Default | Full 13-dimension health check |
fix | --fix | Auto-remediate issues found |
heartbeat | --heartbeat | Quick 3-check pulse (health, embedding, stale) |
benchmark | --benchmark | Score brain against quality benchmarks |
report | --report | Generate and post Slack report |
Workflow
Step 1: Core Diagnostics
Run the full diagnostic suite. doctor --json is the ONLY structured-JSON
health command in v0.4.1; health and stats print text dashboards — parse
what they emit, do not fabricate fields they do not output.
gbrain doctor --json 2>/dev/null
gbrain health
gbrain stats
Dimensions checked
| # | Dimension | Source | Pass criteria |
|---|
| 1 | Page count | gbrain stats / gbrain doctor --json | > 0 |
| 2 | Embedding coverage | gbrain health | > 90% |
| 3 | Stale compiled truths | gbrain search "compiled-truth" --limit 50 + gbrain backlinks <slug> | 0 stale |
| 4 | Orphan pages (no backlinks) | gbrain graph / gbrain backlinks | < 10% of total |
| 5 | Broken internal links | gbrain doctor --json | 0 |
| 6 | Missing citations | gbrain search content scan | < 5% of facts |
| 7 | Filing violations | slug-prefix scan vs filing-rules.md | 0 |
| 8 | Duplicate entities | gbrain call resolve_slugs | 0 |
| 9 | Link density | gbrain stats (links/pages) | healthy ratio |
| 10 | Citation density | gbrain health | within dashboard band |
| 11 | Health composite score | gbrain health | >= 70/100 |
| 12 | Timeline coverage | gbrain timeline <slug> sampling | > 80% entities have timeline |
Step 2: Benchmark Scoring
Compute a weighted composite score:
| Dimension | Weight |
|---|
| Embedding coverage | 25% |
| Citation compliance | 15% |
| Backlink coverage | 20% |
| Filing accuracy | 10% |
| Stale truth ratio | 15% |
| Timeline coverage | 15% |
Grade bands:
- A (90-100): Excellent — no action needed
- B (75-89): Good — minor improvements suggested
- C (60-74): Fair — several issues need attention
- D (40-59): Poor — immediate maintenance required
- F (0-39): Critical — brain is degraded
Step 3: Heartbeat (quick pulse)
For --heartbeat mode, run only:
gbrain health (text dashboard) → parse composite score
gbrain stats → page/link/embedding counts
gbrain search "compiled-truth" + gbrain backlinks <slug> → count stale
Output a one-line status:
Brain: 85/100 | Embeddings: 100% | Stale truths: 0
Step 4: Auto-Remediation (--fix)
When --fix is specified, attempt automatic fixes in order:
- Stale compiled truths: refresh via
gbrain put <slug> (rewrite Compiled Truth from current sources), then gbrain embed --stale
- Missing embeddings:
gbrain embed --stale (incremental; skips already-embedded chunks)
- Orphan pages: suggest backlink candidates (do not auto-delete)
- Broken links: list broken targets for manual resolution
- Missing citations: flag pages for citation review
- Filing violations: suggest correct directories
Never delete pages automatically. Suggest destructive actions for human approval.
Step 5: Report Generation (--report)
Produce a structured markdown report:
# Brain Health Report — {date}
## Summary
- **Score**: {score}/100 ({grade})
- **Pages**: {count}
- **Embedding Coverage**: {pct}%
## Dimension Breakdown
| Dimension | Status | Detail |
|-----------|--------|--------|
| ... | PASS/WARN/FAIL | ... |
## Issues Found
1. {issue description} — {severity} — {suggested fix}
## Actions Taken (if --fix)
1. {action} — {result}
## Recommendations
- {recommendation}
Optionally post to Slack #효정-할일 as a threaded message.
Step 6: Persist Results
Save report to outputs/gbrain-maintain/{date}/report.md.
Save JSON diagnostics to outputs/gbrain-maintain/{date}/diagnostics.json:
{
"date": "YYYY-MM-DD",
"score": 85,
"grade": "B",
"dimensions": { ... },
"issues": [ ... ],
"actions_taken": [ ... ]
}
Conventions
Follow all conventions in gbrain-conventions/:
brain-first.md — always check brain before external APIs
quality.md — citation format, back-linking, notability gate
filing-rules.md — subject-based filing protocol
References
- Upstream:
garrytan/gbrain skills/maintain/SKILL.md
- Local diagnostics:
gbrain doctor --json (structured), gbrain health (text dashboard), gbrain stats
- Composable:
gbrain-ingest, gbrain-briefing, session-preflight