---
name: mikeyobrien/vault-clean
source: https://app.decimal.ai/s/mikeyobrien-vault-clean@1/SKILL.md
source_sha256: 65a90fb6b7d6
---

# Vault Orphan Cleanup

Resolve orphaned notes in `~/.rho/vault/` -- notes that exist but have no inbound `[[wikilinks]]` from any other note.

## Step 1: Detect Orphans

Run the detection script to get the current orphan list:

```bash
TMPDIR="$PREFIX/tmp"

# All note slugs
find ~/.rho/vault -name "*.md" -not -name "_inbox.md" | while read f; do
  basename "$f" .md
done | sort -u > "$TMPDIR/vault-slugs.txt"

# All wikilink targets
rg -oN '\[\[([^\]]+)\]\]' ~/.rho/vault --no-filename -r '$1' | sort -u > "$TMPDIR/vault-links.txt"

# Orphans: notes with zero inbound links
comm -23 "$TMPDIR/vault-slugs.txt" "$TMPDIR/vault-links.txt" | grep -v "^_index$"
```

## Step 2: Triage Each Orphan

For each orphaned note, read it with `vault read` and classify it:

### A. Connect It (most common)
The note has value but nobody links to it. Fix by:
1. Find the right MOC or parent note (check `_index`, project notes, topic MOCs)
2. Add a `[[slug]]` wikilink from the parent to the orphan
3. If the orphan's own `## Connections` section is missing links, add those too

### B. Merge It
The note duplicates content already in another note. Fix by:
1. Identify the canonical note
2. Move any unique content from the orphan into the canonical note
3. Delete the orphan file: `rm ~/.rho/vault/<type>/<slug>.md`

### C. Promote It
The note is important enough to be a new section in `_index.md`. Fix by:
1. Add it to the appropriate section in `_index.md` (Projects, References, Concepts, Patterns, Logs)
2. Ensure the note has a proper `## Connections` section linking back

### D. Delete It
The note is stale, empty, or no longer relevant. Fix by:
1. Verify it's truly not needed (check if any task or active project references it)
2. Delete: `rm ~/.rho/vault/<type>/<slug>.md`
3. Clean up any outbound links from _index or other notes that might reference it

## Step 3: Verify

After processing, rerun the detection script. Orphan count should decrease.
Report: how many connected, merged, promoted, deleted.

## Batch Processing

When running during heartbeat, process max 5 orphans per cycle to stay lightweight.
Prioritize by:
1. Notes linked *from* `_index.md` that don't exist yet (broken links) -- create stubs
2. Recently created orphans (likely just missed during initial capture)
3. Older orphans (may be stale, more likely to delete)

## Common Orphan Patterns

- **Date-prefixed notes** (e.g. `2026-02-05-email-rollback`): Usually operational runbooks. Connect to the relevant project note.
- **Draft content** (e.g. `reddit-localllama-draft`, `x-drafts`): Connect to a drafts MOC or the project they support.
- **Generic names** (`BACKLOG`, `TODO`, `ENGINEERING`): Often subdirectory artifacts from project imports. Usually merge into the project note or delete if redundant.
- **Newly captured notes**: Just need a link from `_index.md` or the relevant MOC.

## Guardrails

- Never delete a note without reading it first
- If unsure whether to delete, connect it instead (safe default)
- Always update `_index.md` when promoting
- After edits, verify the note renders correctly with `vault read`