Obsidian Vault Audit

IDENTITY: Auditor.VaultHygiene. ArchitectureReview➔StructureMap➔SignalScan➔PriorityTriage➔KanbanDecompose. Law: NeverDeleteWithoutReading.NeverAssumeVaultRoot.AlwaysPhase0First. WHENUSE: User says audit/cleanup/reorganize/spring-clean vault|Structural drift|Clutter accumulation. ESPECIALLY:DualWikiArchitecture|IcarusAccretion|OversizedIndexes. NoSkip:Phase0ArchitectureReview|CaseInsensitiveDuplicates|VaultRootVerification. REDFLAGS: DeleteBeforeRead->SampleOrReadFirst|CaseDupOnAPFS->CheckWithStat|KanbanWorkerCrash->CheckEventLogBeforeRedispatch|WikiExtractNoContext->CrossReferenceExistingPages. RATIONALIZATIONS: AllSessionFilesJunk->AgentDecisionsAreHighSignal|FastBulkCleanup->Phase0ArchitectureFirst|KanbanAlwaysWorks->ScriptableOpsBetterInNoAgent. QUICKREF: Phase0(ArchitectureReview{container/wikis/pipeline/drift})➔Phase1(MapStructure)➔Phase2(ScanSignal{icarus/duals/oversized/untitled/empty/datedirs/zerobyte})➔Phase3(Prioritize{P1/P2/P3/P4})➔Phase4(KanbanDecompose)➔Phase5(Verify).

Obsidian Vault Audit

When This Skill Activates

Run this when the user asks to:

• Audit, clean up, or reorganize their Obsidian vault
• "Look through my Obsidian brain"
• "Consolidate, organize, rename, clean up" the vault
• Check for clutter, duplication, or structural problems
• "Spring clean" their notes

Scan Pattern

Phase 0 — Knowledge Architecture Review (Pre-Scan)

Before running file-level scans, step back to assess whether the vault structure is serving its purpose. This phase answers strategic questions that inform the cleanup priorities. See references/knowledge-architecture-review.md for the full checklist and worked examples.

Key framing: The vault is the "second brain" — the agent stores the LLM-Wiki, operational notes, and Fabric entries here. Mnemosyne handles hot auto-injected facts; Obsidian holds everything else. Don't treat it as just a human notebook.

When to run Phase 0 instead of skipping to Phase 1:

• User asks about "how the brain is organized" or "how things are broken up"
• Vault has multiple wikis or knowledge bases
• Vault structure has accumulated organically over months
• User wants to discuss improvements, not just cleanup
• First time auditing this vault

Step 1 — Container audit

Check which containers are active vs archived. Note: PARA structure (0-Inbox, 1-Projects, etc.) was archived on 2026-05-21. Current active structure is: llm-wiki/, icarus/, 3-Resources/, 4-Archive/, Trade Tracking/.

Step 2 — Wiki architecture assessment (for vaults with dual wikis)

Compare wikis side by side:

            Purpose        Content       Schema        Health
Wiki A:     <knowledge>    <N pages>     <style>       <active|stale|empty>
Wiki B:     <operational>  <N pages>     <style>       <active|stale|empty>

Questions to answer:

• Do the wiki purposes overlap? If yes, merger candidate.
• Does one schema reference concepts from the other? (e.g., Team-Wiki tags referencing LLM-Wiki conventions)
• Is one thriving and the other empty? → investigate why (never started? abandoned? superseded?)
• Compare tag taxonomy overlap — same concepts tagged differently?
• Cross-check: do wikilinks exist between the two wikis?

Step 3 — Pipeline flow audit

Track the content lifecycle: External input → Inbox → wiki/project → Archive

Identify where content gets stuck:

• icarus files never promoted to wiki pages
• Inbox items sitting for weeks
• Project notes created but never updated
• Wiki pages created but never cross-linked

High-signal pattern: when icarus/ has 10+ agent-decision files but the wiki has no corresponding pages, that's a curation opportunity.

Step 4 — Icarus curation opportunity assessment

Count and categorize icarus entries by filename pattern:

Step 5 — Architectural drift check

Compare actual structure against any documented plan:

• AGENTS.md or SCHEMA.md files describing intended structure
• Previous session descriptions of vault layout
• Folder names referenced in plans but missing from the filesystem
• Folders existing unreferenced (structural orphans)
• Conventions that diverged (naming patterns, tag formats, frontmatter fields)

Output: A summary delivered before moving to Phase 1:

Vault architecture at a glance:
  • PARA status: Inbox empty, Projects partial (n/N active workstreams covered), Archive has X items needing triage
  • Wiki architecture: <dual|single> — Wiki A is <state>, Wiki B is <state> — <recommendation>
  • Pipeline: Content flowing through Inbox→Wiki? <yes|no> — icarus has X promotable entries
  • Drift: <conventions intact|minor drift|structural drift detected>

Phase 1 — Map the structure

# Full directory layout (3 levels deep, no hidden dirs)
find "$VAULT" -maxdepth 3 -not -path '*/\.*' -type d | sort

# All markdown files
find "$VAULT" -maxdepth 3 -name "*.md" | sort

# All non-md files at root level
ls -p "$VAULT" | grep -v /

# Empty directories
find "$VAULT" -type d -empty -not -path '*/\.*'

Do NOT use the terminal for this — use search_files(target='files') and read_file instead. Terminal is for batch operations only.

Phase 2 — Scan for signal issues

Use this checklist. For each item, the operations list what tools to use:

Phase 3 — Categorize by priority

Use this severity scale:

• 🔴 P1 — Clutter that actively degrades navigation (hundreds of files, duplicates, broken structure)
• 🟠 P2 — Bloat (oversized files, skill-vault redundancy)
• 🟡 P3 — Hygiene (empty dirs, untitled files, naming inconsistencies)
• 🟢 P4 — Polish (convention drift, like a date-folder vs flat daily note)

Phase 4 — Decompose into kanban tasks

Use the kanban-orchestrator pattern:

1. Create one task per priority group (not per issue — keep the board manageable)
2. Assign P1-P2 as independent tasks, P3-P4 can be bundled
3. Set body with: what to scan, what actions to take, what to leave alone

Task body template:

Vault path: <path>
Issue: <description>

Plan:
1. Read affected files/dirs
2. For each: determine keep/archive/delete/merge
3. Document findings in a task comment or log
4. Archive drift to 4-Archive/ when in doubt

Options (if branching):
A) <option 1>
B) <option 2>
C) <option 3>

Phase 5 — Post-cleanup verification

After all kanban tasks complete (or you handle them directly):

# Verify empty dirs are gone
find "$VAULT" -type d -empty -not -path '*/\.*'

# Re-count all files
find "$VAULT" -name "*.md" | wc -l

# Spot-check icarus/
ls -la "$VAULT/icarus/" | wc -l

# Spot-check Sessions/
ls "$VAULT/Sessions/" 2>/dev/null || echo "Sessions/ removed"

Weekly Summary Pattern

For recurring cron-based vault health checks (new/modified notes, attention items, wikilink graph stats), use references/vault-weekly-summary.md. This is a lighter pass than the full audit — stats and highlights, not cleanup decomposition.

Common Cleanup Patterns

Fabric split consolidation

When Fabric tools write to ~/fabric/ but the vault has its own icarus/:

1. Check FABRIC_DIR env var — where does it point?
2. If it points to ~/fabric/ (not the vault), the entries are split
3. Merge ~/fabric/ contents into the vault's icarus/ (skip duplicates)
4. Update FABRIC_DIR to point to the vault's icarus/
5. Verify: fabric_write + fabric_recall still work after change

icarus triage

icarus/ content falls into 3 tiers:
- agent-decision-*.md  → HIGH signal — decisions worth keeping
- agent-session-*.md (non-task) → MEDIUM — cron, research session records
- agent-session-task-*.md → LOW — auto-generated audit records, safe to archive

For decisions: read each, check if knowledge is already in LLM-wiki.
If not, extract key facts → create wiki concept page.
Archive session-task files to 4-Archive/Icarus-Sessions/.

Skill Index split

When 3-Resources/Skills/Skill Index.md exceeds 300 lines:

1. Read the file to understand its structure
2. Split into one *-Index.md per category subdirectory
3. Create a main Skill Index.md that serves as a category directory with [[wikilinks]] to each per-category index
4. Each per-category index lists skills in that category with descriptions

Sessions consolidation

When Sessions/ has Active/, Archive/, and Archived/:

1. Archive/ and Archived/ are the same thing — pick one convention
2. Move Active/ session files into icarus/ (they're session records)
3. Remove Sessions/ entirely — session handling has moved to icarus pattern

Daily note normalization

When daily notes are split (vault's Daily Notes/ vs icarus/daily/):

1. Move icarus/daily/*.md into Daily Notes/
2. Check for date-directories (folders named 2026-04-25/) — convert to flat 2026-04-25.md
3. Remove icarus/daily/ directory

Untitled files cleanup

find "$VAULT" -name "Untitled*" -type f
# For each: read content. If empty/blank, delete.
# If has content, rename meaningfully or triage to Inbox.

Pitfalls

• Case-insensitive filesystem trap: On macOS APFS, llm-wiki/ and LLM-Wiki/ are the same directory. Always check with stat before assuming they're duplicates.
• Don't delete what you didn't read: Always sample or read files before mass-archiving. Some "low-signal" files may contain the only record of a decision.
• Shared state: The icarus/ directory is written to by agents. Any cleanup you do may be partially undone by the next agent cycle. That's OK — periodic cleanup is expected.
• Wiki extraction needs user context: When moving icarus decisions to the wiki, check if the wiki already has the concept before creating a new page. Cross-reference existing pages.
• & in filenames: macOS allows & in filenames. Shell-escape with \& when using cp/mv. Prefer read_file + write_file for these.
• Kanban protocol_violations may be benign: Workers sometimes crash on simple file ops while succeeding on the harder work. Check the task's event log and comment thread before re-dispatching — the work may already be done.
• Always verify the vault root: The vault may be nested (e.g. Hermes Vault/Hermes/ not Hermes Vault/). Always resolve via .obsidian/ or OBSIDIAN_VAULT_PATH.

Verification

After cleanup:

• Every Untitled* file accounted for (renamed, moved, or deleted)
• No dual Archive+Archived folders
• icarus/ count ≤ 20 files
• Daily Notes/ all flat .md files, no date-folders
• Sessions/ removed (content merged into icarus/)
• Oversized index files split to < 50KB each
• Wiki page count updated in index.md
• Vault still opens cleanly in Obsidian (no broken wikilinks introduced)