| name | coherence-sweep |
| description | Run a full coherence sweep across the Brain Dependency Graph - computes staleness, lifecycle transitions, structural health, and generates a report |
| argument-hint | [--days N] [--tensions] [--json] |
| allowed-tools | ["Bash","Read","Write"] |
| user-invocable | true |
| automation | gated |
Brain Coherence Sweep
Run a full coherence analysis of the knowledge base using the Brain Dependency Graph engine. Identifies stale notes, lifecycle transitions, structural issues, and optionally productive tensions.
State Dependencies
| Source | Location | Read | Write | Description |
|---|
| LBS Graph | resources/local-brain-search/data/brain_graph.pkl | ✓ | | NetworkX graph |
| Enrichments | resources/brain-graph/data/graph_enrichments.json | ✓ | ✓ | Node/edge enrichments |
| Reports | resources/brain-graph/reports/ | | ✓ | Generated reports |
Prerequisites
- Brain Dependency Graph must be bootstrapped (
run_brain_graph.sh bootstrap)
- Local Brain Search index must exist
Process
Step 1: Check bootstrap status
cd $PROJECT_ROOT/resources/brain-graph
../local-brain-search/venv/bin/python cli.py status
If not bootstrapped, run bootstrap first:
../local-brain-search/venv/bin/python cli.py bootstrap
Step 2: Run coherence sweep
Default (7-day lookback, lifecycle included, no tensions):
../local-brain-search/venv/bin/python cli.py coherence
With options:
../local-brain-search/venv/bin/python cli.py coherence --tensions
../local-brain-search/venv/bin/python cli.py coherence --days 14
../local-brain-search/venv/bin/python cli.py coherence --json
Step 3: Present results
Read the generated report and present key findings to the user:
- Staleness alerts - Notes that need review due to upstream changes
- Lifecycle transitions - Notes crossing phase boundaries (reflective -> crystallizing -> generative)
- Structural health - Orphans, overloaded hubs, missing MOCs
- Tensions (if enabled) - Productive contradictions for synthesis
Report is saved to: resources/brain-graph/reports/coherence-report-YYYY-MM-DD.md
Output Format
Present a concise summary with:
- Count of stale notes with top 5 most affected
- Notable lifecycle transitions (especially new generative notes)
- Structural issues requiring attention
- Path to full report
