---
name: Vault Health
slug: vault-health
category: Quality
description: Vault Health runs condition-based vault diagnostics across schema, orphans, links, description quality, three-space boundaries, throughput, stale notes, and MOC coherence. It supports quick, full, and three-space modes and returns actionable FAIL/WARN/PASS reports.
github: "https://github.com/agenticnotetaking/arscontexta/tree/main/skills/health"
language: Shell
stars: 3473
forks: 219
install: "npx degit https://github.com/agenticnotetaking/arscontexta/tree/main/skills/health ~/.claude/skills/health"
installs_to: ~/.claude/skills/health
source_path: skills/health/SKILL.md
collection_size: 25
category_size: 1354
collection_url: "https://dirskills.com/collections/agenticnotetaking/arscontexta"
added: 2026-08-16T07:02:37.760Z
last_synced: 2026-08-16T07:02:37.760Z
canonical_url: "https://dirskills.com/skills/vault-health"
---

# Vault Health

Vault Health runs condition-based vault diagnostics across schema, orphans, links, description quality, three-space boundaries, throughput, stale notes, and MOC coherence. It supports quick, full, and three-space modes and returns actionable FAIL/WARN/PASS reports.

**Install:**

```bash
npx degit https://github.com/agenticnotetaking/arscontexta/tree/main/skills/health ~/.claude/skills/health
```

## README

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

4. **Templates** — read template files to understand required schema fields for validation

If these files don't exist (pre-init invocation or standalone use), use universal defaults:
- notes folder: `notes/`
- inbox folder: `inbox/`
- topic map: topic maps in notes/

---

## EXECUTE NOW

**Target: $ARGUMENTS**

Parse the invocation mode immediately:

| Input | Mode | Categories Run |
|-------|------|---------------|
| empty or `quick` | Quick | 1 (Schema), 2 (Orphans), 3 (Links) |
| `full` | Full | All 8 categories |
| `three-space` | Three-Space | 5 (Three-Space Boundaries) only |

**Execute these steps:**

1. **Detect mode** from arguments
2. **Scan the vault** — inventory all note files, {vocabulary.topic_map} files, inbox items, ops files
3. **Run each applicable diagnostic category** in order (1-8)
4. **Classify each result** as PASS, WARN, or FAIL using the thresholds below
5. **Surface condition-based maintenance signals** (check against threshold table)
6. **Generate the health report** with specific file paths, counts, and recommended actions
7. **Write report to** `ops/health/YYYY-MM-DD-report.md`

**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"
  # Check: description field present
  rg -q '^description:' "$f" || echo "WARN: $f — missing description field"
  # Check: topics field present and links to at least one topic map
  rg -q '^topics:' "$f" || echo "WARN: $f — missing topics field"
done
```

**Additional checks:**
- Domain-specific enum fields have valid values (check against template `_schema` blocks if templates exist)
- `description` field is non-empty (not just present)
- `topics` field contains at least one wiki link

**If `validate-kernel.sh` exists** in `${CLAUDE_PLUGIN_ROOT}/reference/`, run it and include results.

**Thresholds:**

| Condition | Level |
|-----------|-------|
| Any note missing YAML frontmatter | FAIL |
| Any note missing `description` field | WARN |
| Any note missing `topics` field | WARN |
| Any invalid enum value | WARN |
| All notes pass all checks | PASS |

**Output format:**
```
[1] Schema Compliance ............ WARN
    2 notes missing description:
      - notes/example-note.md
      - notes/another-note.md
    1 note missing topics:
      - notes/orphaned-claim.md
    12/15 notes fully compliant
```

### Category 2: Orphan Detection (quick, full)

**What it checks:** Every {vocabulary.note} has at least one incoming wiki link from another file.

**How to check:**

```bash
# For each note file, check if ANY other file links to it
for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  basename=$(basename "$f" .md)
  # Search for [[basename]] in all other files
  count=$(rg -l "\[\[$basename\]\]" --glob '*.md' | grep -v "$f" | wc -l | tr -d ' ')
  if [[ "$count" -eq 0 ]]; then
    echo "WARN: $f — no incoming links (orphan)"
  fi
done
```

**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]
      - notes/old-observation.md (created 5d ago) [WARN]
      - notes/forgotten-insight.md (created 14d ago) [FAIL]
    Recommendation: run /reflect on forgotten-insight.md and old-observation.md
```

### Category 3: Link Health (quick, full)

**What it checks:** Every wiki link `[[target]]` in every file resolves to an existing file.

**How to check:**

```bash
# Extract all wiki links from all markdown files
# For each unique link target, verify a file with that name exists
rg -oN '\[\[([^\]]+)\]\]' --glob '*.md' -r '$1' | sort -u | while read target; do
  # Search for file matching this name
  found=$(find . -name "$target.md" -not -path "./.git/*" 2>/dev/null | head -1)
  if [[ -z "$found" ]]; then
    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
```

### Category 5: Three-Space Boundary Check (full, three-space)

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

**Detection:**
```bash
# Check for ops-pattern YAML fields in notes
rg '^(current_phase|completed_phases|batch|source_task|queue_id):' {vocabulary.notes}/ --glob '*.md'
# Check for task file patterns in notes
rg '## (Create|Reflect|Reweave|Verify|Enrich)$' {vocabulary.notes}/ --glob '*.md'
```

| Found | Level |
|-------|-------|
| Any ops-pattern content in {vocabulary.notes}/ | WARN |

#### 5b. Self into Notes (Identity Pollution)

Agent identity or methodology content mixed into user's knowledge graph. Agent's operational observations appearing in user's {vocabulary.notes}/ space.

**Detection:**
```bash
# Check for agent-reflection patterns in notes (methodology observations, workflow assessments)
rg -i '(my methodology|I observed that|agent reflection|session learning|I learned)' {vocabulary.notes}/ --glob '*.md'
```

| Found | Level |
|-------|-------|
| Any agent-reflection content in {vocabulary.notes}/ | WARN |

#### 5c. Notes into Ops (Trapped Knowledge)

Genuine insights trapped in session logs, observations, or ops files that should be promoted to {vocabulary.notes}/.

**Detection:**
```bash
# Check for claim-like content in ops that could be notes
# Look for files with description fields in ops/observations/ or ops/methodology/
rg '^description:' ops/observations/*.md ops/methodology/*.md 2>/dev/null
```

| Found | Level |
|-------|-------|
| Content in ops/ with note-like schema (description + topics) | INFO (may be intentional, flag for review) |

#### 5d. Self into Ops / Ops into Self

Temporal state stored in self/ (should be in ops/), or identity content stored in ops/ (should be in self/).

**Detection:**
```bash
# Check for temporal/queue content in self/
rg '^(current_phase|status|queue):' self/ --glob '*.md' 2>/dev/null
# Check for identity content in ops/
rg -i '(my identity|I am|who I am|my personality)' ops/ --glob '*.md' 2>/dev/null
```

#### 5e. Notes into Self

Domain knowledge stored in self/ instead of {vocabulary.notes}/.

**Detection:**
```bash
# Check self/memory/ for notes that have topics linking to notes-space topic maps
rg '^topics:.*\[\[' self/memory/*.md 2>/dev/null | grep -v 'identity\|methodology\|goals\|relationships'
```

#### 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/
if [[ ! -d "self/" ]]; then
  # Check for goals or handoff content in notes/
  rg -i '(my goals|current goals|handoff|session handoff)' {vocabulary.notes}/ --glob '*.md'
fi
```

**Thresholds:**

| Condition | Level |
|-----------|-------|
| Any boundary violation (5a, 5b, 5d, 5e) | WARN |
| Trapped knowledge in ops (5c) | INFO |
| Self-absence effects (5f) | WARN |
| All boundaries intact | PASS |

**Output format:**
```
[5] Three-Space Boundaries ....... WARN
    1 boundary violation detected:
      Ops into Notes (infrastructure creep):
        - notes/task-tracking.md contains queue state fields (current_phase, batch)
        - Should be in ops/queue/ not notes/
    1 potential trapped knowledge:
      - ops/observations/interesting-pattern.md has note-like schema
        Consider promoting to notes/ via /reduce or direct creation
    Recommendation: move task-tracking.md to ops/queue/
```

### Category 6: Processing Throughput (full only)

**What it checks:** The inbox-to-knowledge ratio. High ratios indicate collector's fallacy — capturing more than processing.

**How to check:**

```bash
# Count items in each space
INBOX_COUNT=$(find {vocabulary.inbox}/ -name '*.md' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')
NOTES_COUNT=$(find {vocabulary.notes}/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
QUEUE_COUNT=$(find ops/queue/ -name '*.md' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')

# Calculate ratio
if [[ $((INBOX_COUNT + NOTES_COUNT)) -gt 0 ]]; then
  RATIO=$((INBOX_COUNT * 100 / (INBOX_COUNT + NOTES_COUNT)))
else
  RATIO=0
fi

echo "Inbox: $INBOX_COUNT | Notes: $NOTES_COUNT | In-progress: $QUEUE_COUNT | Ratio: ${RATIO}%"
```

**Thresholds:**

| Condition | Level |
|-----------|-------|
| Inbox-to-total ratio > 75% (3:1 inbox to notes) | FAIL |
| Inbox-to-total ratio > 50% | WARN |
| Inbox items > 20 | WARN (regardless of ratio) |
| Inbox-to-total ratio <= 50% AND inbox <= 20 | PASS |

**Output format:**
```
[6] Processing Throughput ........ WARN
    inbox: 12 | notes: 8 | in-progress: 3 | ratio: 60%
    Inbox items outnumber processed notes — collector's fallacy risk
    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

```bash
for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  basename=$(basename "$f" .md)

  # Last modified (days ago)
  mod_days=$(( ($(date +%s) - $(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)) / 86400 ))

  # Incoming link count
  incoming=$(rg -l "\[\[$basename\]\]" --glob '*.md' | grep -v "$f" | wc -l | tr -d ' ')

  if [[ $mod_days -gt 30 ]] && [[ $incoming -lt 2 ]]; then
    echo "STALE: $f — $mod_days days old, $incoming incoming links"
  fi
done
```

**Thresholds:**

| Condition | Level |
|-----------|-------|
| Any note > 30 days old with < 2 incoming links | WARN |
| Any note > 90 days old with 0 incoming links | FAIL |
| All notes either recent or well-connected | PASS |

**Prioritization:** Sort stale notes by:
1. Age (oldest first)
2. Link density (least connected first)
3. Topic relevance (notes in active topic areas are higher priority)

**Output format:**
```
[7] Stale Notes .................. WARN
    4 stale notes detected (>30d old, <2 incoming links):
      - notes/old-observation.md (92d, 0 links) [FAIL — consider archiving or reweaving]
      - notes/early-claim.md (45d, 1 link) [WARN]
      - notes/setupial-thought.md (38d, 1 link) [WARN]
      - notes/first-draft.md (31d, 0 links) [WARN]
    Recommendation: run /reweave on these notes to find connections, or archive if no longer relevant
```

### Category 8: {vocabulary.topic_map} Coherence (full only)

**What it checks:** Each {vocabulary.topic_map} has a healthy number of linked notes, and notes in the same topic area are actually linked.

**How to check:**

For each {vocabulary.topic_map} file:
1. Count notes that link TO this {vocabulary.topic_map} (notes with this in their `topics` footer/field)
2. Check if there are notes in the same topic area NOT linked to the {vocabulary.topic_map} (coverage gaps)
3. Verify context phrases exist on Core Ideas links (not bare links)

```bash
# For each topic map
for moc in {vocabulary.notes}/*.md; do
  [[ -f "$moc" ]] || continue
  # Check if this is a topic map (has type: moc in frontmatter)
  rg -q '^type: moc' "$moc" || continue

  moc_name=$(basename "$moc" .md)

  # Count notes linking to this topic map
  note_count=$(rg -l "\[\[$moc_name\]\]" {vocabulary.notes}/ --glob '*.md' | grep -v "$moc" | wc -l | tr -d ' ')

  echo "$moc_name: $note_count notes"
done
```

**Thresholds:**

| Condition | Level |
|-----------|-------|
| {vocabulary.topic_map} with < 5 notes | WARN (underdeveloped — consider merging into parent) |
| {vocabulary.topic_map} with > 50 notes | WARN (oversized — consider splitting into sub-{vocabulary.topic_maps}) |
| {vocabulary.topic_map} with > 40 notes | INFO (approaching threshold) |
| Notes exist in topic area but not linked to {vocabulary.topic_map} | WARN (coverage gap) |
| All {vocabulary.topic_maps} in 5-50 range with good coverage | PASS |

**Context phrase check:**

```bash
# Check for bare links in topic map Core Ideas (links without context phrases)
for moc in {vocabulary.notes}/*.md; do
  rg -q '^type: moc' "$moc" || continue
  # Look for "- [[note]]" without " — " context
  rg '^\s*- \[\[' "$moc" | grep -v ' — ' | grep -v '^\s*- \[\[.*\]\].*—'
done
```

Bare links without context phrases are address book entries, not navigation. Every link in a {vocabulary.topic_map} should explain WHY to follow it.

**Output format:**
```
[8] MOC Coherence ................ WARN
    3 topic maps checked:
      - knowledge-work: 28 notes [PASS]
      - graph-structure: 52 notes [WARN — oversized, consider splitting]
        3 bare links without context phrases
      - agent-cognition: 3 notes [WARN — underdeveloped, consider merging]
    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.

| Condition | Threshold | Recommendation |
|-----------|-----------|---------------|
| Pending observations | >= 10 files in ops/observations/ | Consider running /rethink |
| Open tensions | >= 5 files in ops/tensions/ | Consider running /rethink |
| Inbox items | >= 3 items | Consider /reduce or /pipeline |
| Unprocessed sessions | >= 5 files in ops/sessions/ | Consider /remember --mine-sessions |
| Orphan notes | Any persistent (> 7d) | Run /reflect on orphaned notes |
| Dangling links | Any | Fix broken references immediately |
| Stale notes | Low links + old | Consider /reweave |
| {vocabulary.topic_map} oversized | > 40 notes | Consider splitting |
| Queue stalled | Tasks pending > 2 sessions without progress | Surface as blocked |
| Trigger coverage gap | Known maintenance condition has no configured trigger | Flag gap itself |

**How to check condition counts:**

```bash
# Pending observations
OBS_COUNT=$(find ops/observations/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# Open tensions
TENSION_COUNT=$(find ops/tensions/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# Inbox items
INBOX_COUNT=$(find {vocabulary.inbox}/ -name '*.md' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')

# Unprocessed sessions
SESSION_COUNT=$(find ops/sessions/ -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# Queue stalled
PENDING_TASKS=$(jq '[.tasks[] | select(.status=="pending")] | length' ops/queue/queue.json 2>/dev/null || echo 0)
```

**The meta-trigger:** Include a "trigger coverage" check. Compare known maintenance conditions against what is actually being chec