$ npx -y skills add agenticnotetaking/arscontexta --skill health --agent claude-code
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/health
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Run condition-based vault health diagnostics. 8 categories — schema compliance, orphan detection, link health, description quality, three-space boundaries, processing throughput, stale notes, MOC coherence. 3 modes — quick (schema+orphans+links), full (all 8), three-space
📊 Stats
Stars3,451
Forks218
LanguageShell
LicenseMIT
📦 Ships with arscontexta
</> SKILL.md
health.SKILL.md
---name: health
description: Run condition-based vault health diagnostics. 8 categories — schema compliance, orphan detection, link health, description quality, three-space boundaries, processing throughput, stale notes, MOC coherence. 3 modes — quick (schema+orphans+links), full (all 8), three-space (boundary violations only). Returns actionable FAIL/WARN/PASS report with specific fixes ranked by impact. Triggers on "/health", "check vault health", "maintenance report", "what needs fixing".
version: "1.0"
generated_from: "arscontexta-v1.6"
context: fork
model: opus
allowed-tools: Read, Grep, Glob, Bash, mcp__qmd__vector_search
argument-hint: "[optional: 'quick', 'full', or 'three-space']"
---## Runtime Configuration (Step 0 — before any processing)
Read these files to configure domain-specific behavior:
1. **`ops/derivation-manifest.md`** — vocabulary mapping, folder names, platform hints
- Use `vocabulary.notes` for the notes folder name
- Use `vocabulary.inbox` for the inbox folder name
- Use `vocabulary.note` for the note type name in output
- Use `vocabulary.topic_map` for MOC/topic map references
- Use `vocabulary.topic_maps` for plural form
2. **`ops/config.yaml`** — processing depth, thresholds
3. **Three-space reference** — `${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md` for boundary rules (load only for full and three-space modes)
**START NOW.** Reference below explains each diagnostic category in detail.
### Platform Adaptation
Checks adapt to what the platform supports:
- If semantic search (qmd) is not configured, skip semantic-dependent checks and note their absence
- If hooks are not available, note that validation is convention-only (no automated enforcement)
- If self/ directory does not exist (disabled by config), skip self-space checks but verify ops/ absorbs self-space content correctly
**Report what CAN be checked, not what the platform lacks.**
---
## The 8 Diagnostic Categories
### Category 1: Schema Compliance (quick, full)
**What it checks:** Every {vocabulary.note} in {vocabulary.notes}/ and self/memory/ (if self/ is enabled) has valid YAML frontmatter with required fields.
**How to check:**
```bash
# Find all note files (exclude topic maps)
for f in {vocabulary.notes}/*.md; do
[[ -f "$f" ]] || continue
# Check: YAML frontmatter exists
head -1 "$f" | grep -q '^---$' || echo "FAIL: $f — no YAML frontmatter"
**Nuance:** Orphans are not automatically failures. A note created today that hasn't been through /{vocabulary.cmd_reflect} yet is expected to be orphaned temporarily. Check file age:
| Condition | Level |
|-----------|-------|
| Orphan note created < 24 hours ago | INFO (expected — awaiting reflect phase) |
| Orphan note created 1-7 days ago | WARN |
| Orphan note older than 7 days | FAIL (persistent orphan needs attention) |
| No orphans detected | PASS |
**Output format:**
```
[2] Orphan Detection ............. WARN
3 orphan notes detected:
- notes/new-claim.md (created 2h ago — awaiting reflect) [INFO]
echo "FAIL: dangling link [[${target}]] — no file found"
# Show which files contain this dangling link
rg -l "\[\[$target\]\]" --glob '*.md'
fi
done
```
**Thresholds:**
| Condition | Level |
|-----------|-------|
| Any dangling link (target does not exist) | FAIL |
| All links resolve | PASS |
**Why FAIL not WARN:** Dangling links are broken promises. Every `[[link]]` a reader follows that leads nowhere erodes trust in the graph. Fix these immediately.
**Output format:**
```
[3] Link Health .................. FAIL
2 dangling links found:
- [[nonexistent-note]] referenced in:
- notes/some-claim.md (line 14)
- notes/another-claim.md (line 8)
- [[removed-topic]] referenced in:
- notes/old-note.md (line 22)
Recommendation: create missing notes or remove broken links
```
### Category 4: Description Quality (full only)
**What it checks:** Every {vocabulary.note}'s description adds genuine information beyond the title — not just a restatement.
**How to check:**
For each {vocabulary.note}:
1. Read the title (filename without extension)
2. Read the `description` field from YAML frontmatter
3. Evaluate: does the description add scope, mechanism, or implication that the title does not cover?
**Quality heuristics:**
| Check | Threshold |
|-------|-----------|
| Description length | 50-200 chars ideal. < 30 chars = too terse. > 250 chars = too verbose |
| Restatement detection | If description uses >70% of the same words as the title = restatement |
| Information added | Description should mention mechanism, scope, or implication not in title |
**Thresholds:**
| Condition | Level |
|-----------|-------|
| Description is a clear restatement of the title | WARN |
| Description is < 30 characters | WARN |
| Description is missing entirely | WARN (also caught by Category 1) |
| Description adds genuine new information | PASS |
**This check requires judgment.** Use semantic understanding, not just string matching. A description that uses different words but says the same thing as the title is still a restatement.
**Output format:**
```
[4] Description Quality .......... WARN
2 descriptions are restatements:
- notes/quality-matters.md
Title: "quality matters more than quantity"
Description: "quality is more important than quantity in knowledge work"
Issue: restates title without adding mechanism or implication
- notes/structure-helps.md
Title: "structure without processing provides no value"
Description: "having structure without processing it is not valuable"
Issue: exact restatement
Recommendation: rewrite descriptions to add scope, mechanism, or implication
**What it checks:** Content respects the boundaries between self/, {vocabulary.notes}/, and ops/. Each space has a purpose — conflating them degrades search quality, navigation, and trust.
**Before running this check:** Read `${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md` for the full boundary specification.
**Six conflation patterns to detect:**
#### 5a. Ops into Notes (Infrastructure Creep)
Queue state, health metrics, task files, or processing artifacts appearing in {vocabulary.notes}/ directory.
#### 5f. Self Space Absence Effects (when self/ is disabled)
When self/ is disabled, verify ops/ absorbs self-space content correctly. Check that goals and handoffs are in ops/, not floating in {vocabulary.notes}/.
**Detection:**
```bash
# If self/ doesn't exist, check that goals/handoffs are in ops/
Recommendation: run /reduce on oldest inbox items or /pipeline for end-to-end processing
```
### Category 7: Stale Note Detection (full only)
**What it checks:** Notes not modified recently AND with low link density. Staleness is condition-based (low link density + no activity since N new notes were added), not purely calendar-based.
**How to check:**
For each {vocabulary.note}:
1. Check last modified date (`stat` or `git log`)
2. Count incoming links (same as orphan detection, but counting instead of boolean)
3. Flag notes with: modified > 30 days ago AND < 2 incoming links
Recommendation: split graph-structure into sub-topic-maps; add context phrases to bare links
```
---
## Condition-Based Maintenance Signals
After running all applicable diagnostic categories, check these condition-based triggers. These are NOT the 8 categories above — they are cross-cutting signals that suggest specific skill invocations.
**The meta-trigger:** Include a "trigger coverage" check. Compare known maintenance conditions against what is actually being checked. If a maintenance condition has no corresponding check or trigger configured, that gap itself is a finding. This prevents the failure mode where maintenance debt accumulates undetected.
---
## Output Format
The complete health report follows this structure. Every report, regardless of mode, uses this format.
[details — note count per topic map, coverage gaps, bare links]
---
Maintenance Signals:
[condition-based triggers from table above, if any thresholds met]
- observations: N pending (threshold: 10) [TRIGGERED | OK]
- tensions: N pending (threshold: 5) [TRIGGERED | OK]
- inbox: N items (threshold: 3) [TRIGGERED | OK]
- sessions: N unprocessed (threshold: 5) [TRIGGERED | OK]
---
Recommended Actions (top 3, ranked by impact):
1. [Most impactful action — specific command + specific file]
2. [Second priority — specific command + specific file]
3. [Third priority — specific command + specific file]
=== END REPORT ===
```
### Report Storage
Write every health report to `ops/health/YYYY-MM-DD-report.md`. If multiple reports are run on the same day, append a counter: `YYYY-MM-DD-report-2.md`.
This creates a health history that /architect can reference when proposing evolution. Trends across reports reveal systemic patterns that individual reports miss.
---
## Quality Standards
### Be Specific
Every finding MUST name the specific file(s) involved.
Bad: "some notes lack descriptions"
Good: "notes/example-note.md and notes/another-note.md are missing the description field"
Bad: "there are dangling links"
Good: "[[nonexistent-claim]] is referenced in notes/old-note.md (line 14) and notes/related.md (line 22) but no file with that name exists"
### Prioritize by Impact
Not all issues are equal. The recommended actions section ranks by impact:
| Impact Tier | Examples | Why |
|------------|---------|-----|
| Highest | Dangling links, persistent orphans | Broken promises in the graph — readers hit dead ends |
| High | Schema violations, boundary violations | Structural integrity — compounds into larger problems |
| Medium | Description quality, stale notes | Retrieval quality — degraded but not broken |
| Low | {vocabulary.topic_map} size warnings, throughput ratio | Maintenance debt — matters at scale |
### Don't Overwhelm
- Focus on the top 5-10 issues in the recommended actions
- Group related issues (3 notes missing descriptions = 1 finding, not 3)
- For large vaults, cap per-category detail at 10 specific files, then summarize: "...and 15 more"
### Distinguish FAIL from WARN
| Level | Meaning | Action Required |
|-------|---------|----------------|
| FAIL | Structural issue — something is broken | Fix before it compounds |
| WARN | Improvement opportunity — something is suboptimal | Address when convenient |
| PASS | Category is healthy | No action needed |
| INFO | Noteworthy but not actionable | Context for understanding |
/health (diagnose) -> specific findings -> specific skill invocation -> /health (verify fix)
```
Health is diagnostic only — it measures state without prescribing changes. /architect reads health reports and proposes changes with research backing. The separation matters: health tells you WHAT is wrong, architect tells you WHY and HOW to fix it.
