Vault Health

---
name: vault-health
description: >
  Vault infrastructure diagnostics with actionable recommendations.
  Use when: "check vault health", "vault status", "run health check", "check sync status",
  "agent memory stats", "is the vault healthy", "skills health", "skill audit", "skills report".
  PROACTIVE TRIGGER (CONDITIONAL): Before or after major vault operations, at session start
  if vault issues are suspected, or monthly for skills audit (on whatever cadence you choose).
version: 3.0.0
---

# Vault Health Check

Run comprehensive diagnostics on the notes vault and present findings with actionable recommendations. This is a read-only operation, never modify vault files during a health check.

## Prerequisites

- Working directory: `<HOME>/Documents/<NOTES_ROOT>/`

## Procedure

### Step 1: Run Health Check Script

```bash
node "<automation-script>" health-check
```

This writes `<HEALTH_REPORT>` with automated checks. Read it.

### Step 2: Present the Report

Format findings cleanly:

```
VAULT HEALTH REPORT
===================
Generated: YYYY-MM-DD HH:MM

INFRASTRUCTURE
  Notes sync:       PASS   synced within last 24h
  File Count:       PASS   <N> markdown files
  Notion Sync:      WARN   last sync <N> days ago
  Daily Scheduler:  PASS   launchd loaded, last run today <HH:MM>

BACKFILL STATUS
  Backfill:         INFO   in progress, <N> items remaining

AGENT MEMORY
  <agent>:   PASS   <N> session logs, memory.md <N> lines
  ...

INBOX
  Items waiting:    <N> files in inbox/

Overall: <N> WARN, <N> FAIL
```

**Status meanings:**
- **PASS**, healthy, no action needed
- **INFO**, expected state, informational only (e.g., backfill in progress on a new vault)
- **WARN**, needs attention. Provide a specific fix.
- **FAIL**, broken. Provide an immediate fix.

### Step 3: Provide Recommendations

For each WARN or FAIL, consult `references/troubleshooting.md` for the specific fix command or action. Present fixes inline, not just "check the thing" but the exact command to run.

If everything passes, keep it brief: "All clear. No issues found."

Always show inbox count as a useful nudge without being alarming.

### Step 4: Optional Deep Checks

Only run when user explicitly asks for "deep check" or "full audit":

1. **Folder structure audit**, scan for files outside conventional folders
2. **Frontmatter coverage**, sample 20 random .md files, check for valid frontmatter, report percentage
3. **Orphaned files**, files not linked from any index
4. **Config validation**, parse the automation config, verify remote page ids and folder paths
5. **Duplicate detection**, check for duplicate `notion-id` values in frontmatter

Report deep check results separately with their own status levels.

## Rules

- Read-only operation, never modify vault files during health check
- Present findings clearly and concisely
- Do not alarm about INFO items, they are expected states on a new vault
- `<HEALTH_REPORT>` is auto-generated, do not treat it as user content
- Always include inbox item count in report

## Step 5: Skills Health (run when user asks for "skills health" or during monthly audit)

Audit the skills system and report on trigger coverage, usage, and health.

### 5a: Trigger Tier Distribution

Scan all `~/.claude/skills/*/SKILL.md` files and categorize by trigger quality:

| Tier | Criteria | Count |
|------|----------|-------|
| **Always-on** | Has `MANDATORY` in description | N |
| **Proactive** | Has `PROACTIVE TRIGGER (CRITICAL)` | N |
| **Contextual** | Has `PROACTIVE TRIGGER (CONDITIONAL)` | N |
| **On-demand** | Has `Use when:` but no PROACTIVE | N |
| **No triggers** | Missing both `Use when:` and `PROACTIVE` | N |

### 5b: Usage Report

For each skill, read the `last_used` field:
- List skills not used in 60+ days (candidates for trigger improvement)
- List skills never used (check if triggers are missing or too vague)
- Top 10 most recently used skills

### 5c: Missing Triggers

Flag skills where:
- Description has no "Use when:" keywords
- Description mentions "Proactively suggest" in prose but has no formal `PROACTIVE TRIGGER` label
- Hooks are described in text but missing from YAML `hooks:` section

### 5d: Recommendations

For each flagged skill, suggest:
- Specific trigger keywords to add
- Whether it should be PROACTIVE (CRITICAL) or (CONDITIONAL)
- Whether it needs a hook

### Report Format

```
SKILLS HEALTH
=============
Total skills: N
Trigger coverage: N% (skills with proper triggers / total)

TIER DISTRIBUTION
  Always-on:    N
  Proactive:    N
  Contextual:   N
  On-demand:    N
  No triggers:  N  [WARN if > 0]

USAGE (last 60 days)
  Active:       N skills used
  Dormant:      N skills not used
  Never used:   N skills

TOP CONCERNS
  [List skills with missing triggers or stale usage]

RECOMMENDATIONS
  [Specific fixes for top 5 flagged skills]
```

Write the full report to `<reports-dir>/skills-audit-YYYY-MM.md`

## Additional Resources

### Reference Files

- **`references/troubleshooting.md`**, Fix commands for every WARN/FAIL type, deep check procedures, and common resolution patterns

# Troubleshooting Reference

Fix commands and resolution patterns for every health check status.

## WARN/FAIL Fix Table

| Status | Issue | Fix |
|--------|-------|-----|
| WARN | Notes sync stale (>24h) | Open the notes app on the primary machine and wait for sync. Check Settings > Sync for errors. |
| WARN | Notion Sync stale (>48h) | Run: `node "<automation-script>" notion-sync`, if it fails, check `<automation-env-file>` has a valid token |
| WARN | memory.md over 140 lines | Compact the affected agent's memory |
| WARN | Daily scheduler not loaded | Run: `launchctl load ~/Library/LaunchAgents/<automation-job>.plist` |
| WARN | Daily run missed (>24h) | Run: `launchctl start <automation-job>` then `tail -f <automation-log-file>` to check for errors |
| WARN | Too many session logs (>30) | Archive the old ones |
| FAIL | Notion token invalid/missing | Create integration at https://www.notion.so/profile/integrations, paste token in `<automation-env-file>` |
| FAIL | Scripts directory missing | `system/scripts/` was deleted, needs investigation and rebuild |
| FAIL | automation config missing/corrupt | Rebuild from the automation script's defaults or restore from git |
| INFO | Backfill incomplete | Normal for new vaults. Runs on the schedule you configure. No action needed. |
| INFO | Inbox has items | Triage the inbox when convenient |
| INFO | Agent has no session logs | Normal for agents not yet actively used (e.g., secondary-machine agents) |

## Scheduler Diagnostics

Check if the scheduler is loaded:
```bash
launchctl list | grep vault
```

Trigger a manual run:
```bash
launchctl start <automation-job>
```

Watch output in real-time:
```bash
tail -f <automation-log-file>
```

Verify the schedule (the hour in the plist should match your configured run time):
```bash
grep -A5 StartCalendarInterval ~/Library/LaunchAgents/<automation-job>.plist
```

Reload after editing plist:
```bash
launchctl unload ~/Library/LaunchAgents/<automation-job>.plist
launchctl load ~/Library/LaunchAgents/<automation-job>.plist
```

## Deep Check Procedures

### Folder Structure Audit

Scan for files outside conventional folders:
```bash
find "<HOME>/Documents/<NOTES_ROOT>/" -name "*.md" -maxdepth 1
```
Any .md files at the vault root (outside known folders) are rogue and should be triaged.

### Frontmatter Coverage

Sample 20 random .md files and check for:
- `type` field (required)
- `created` field (required)
- `modified` field (required)
- `tags` field (required)

Report as percentage: "85% coverage (17/20 files have valid frontmatter)"

Files most likely to lack frontmatter: old inbox items, manually created notes, imported content.

### Orphaned Files

Check for .md files not referenced by any index or wikilinked from other notes. Common in:
- `resources/` after migration
- `areas/` when index.md wasn't updated
- `inbox/` items that were manually moved without updating references

### Config Validation

Parse the automation config and verify:
- Every configured remote page id is well formed
- Every mapped folder path exists on disk
- The backfill flag matches the actual state
- No entry is registered twice across the configured collections

### Duplicate Detection

Scan all .md files for `notion-id` in frontmatter. Report any duplicates, these would cause sync conflicts where one file overwrites another.

## Common Resolution Patterns

**"Notion sync keeps failing"**
1. Check token: `grep NOTION_TOKEN <automation-env-file>`
2. Test token: `curl -s -H "Authorization: Bearer YOUR_TOKEN" -H "Notion-Version: 2022-06-28" https://api.notion.com/v1/users/me`
3. If 401: token expired or revoked. Create new integration.
4. If 403: integration not shared with the pages. Share pages with integration in Notion.

**"launchd job never runs"**
1. The machine must be awake at the scheduled hour
2. Check `RunAtLoad` is false (correct, avoids running on every login)
3. Verify plist is in `~/Library/LaunchAgents/` (not `/Library/LaunchAgents/`)
4. Check log: `tail -20 <automation-log-file>`