gbrain-maintain

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   # connectivity + schema + page count (structured)
gbrain health                      # text dashboard: composite score + dimensions
gbrain stats                       # page/link/tag counts

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:

1. gbrain health (text dashboard) → parse composite score
2. gbrain stats → page/link/embedding counts
3. 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:

1. Stale compiled truths: refresh via gbrain put <slug> (rewrite Compiled Truth from current sources), then gbrain embed --stale
2. Missing embeddings: gbrain embed --stale (incremental; skips already-embedded chunks)
3. Orphan pages: suggest backlink candidates (do not auto-delete)
4. Broken links: list broken targets for manual resolution
5. Missing citations: flag pages for citation review
6. 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