obsidian-audit

name	obsidian-audit
description	Audit the Obsidian vault for organizational health — broken links, naming violations, misplaced notes, sync status, stale content, and connection quality

Obsidian Vault Audit

Run this periodically or after large note-creation sessions to ensure the vault stays healthy and useful.

When to Run

• After any session creating 3+ notes, or after a subagent creates vault content
• Weekly if the vault is actively growing
• On request, or when sync issues are suspected

Audit Checklist

Perform each check in order. Report findings in the scorecard at the end.

1. Sync Health

tail -3 ~/.agent-configs/hooks/sync.log   # sync runs on a 5-min scheduler; entries must be recent
git -C ~/obsidian_notes status
git -C ~/obsidian_notes log --oneline origin/main..HEAD
git -C ~/obsidian_notes log --oneline HEAD..origin/main

Pass: last sync.log entry within ~10 minutes, no stuck uncommitted files, local and remote in sync.

2. Folder Placement

find ~/obsidian_notes -name "*.md" -not -path "*/.obsidian/*" -not -path "*/.git/*" | sort

Check every file:

• inbox/ — unsorted, temporary. Anything >2 weeks old is stale.
• projects/ — time-bound work (grouped by project: frontmatter, no hub files).
• areas/ — durable domain knowledge (promoted from projects/ when reused).
• library/ — atomic reference notes, papers, tools.
• personal/ — goals, journal, personal context.
• agent/ — session-log, open-questions, connections, instincts, context files.

Flag: Any .md in vault root (except README.md). Any note mismatching its folder's purpose.

3. Subfolder Structure & Frontmatter Grouping

• Projects with 2+ notes MUST use a subfolder (e.g., projects/teknofest/)
• No _index.md hub files. Project grouping uses project: frontmatter.
• Every note in projects/ MUST have a project: field in frontmatter.
• No prefix-based flat naming (projects/proj-arch.md, projects/proj-bugs.md)
• Do NOT create generic hub filenames (Home.md, _index.md, index.md). Use descriptive project-prefixed names.

Flag: Notes in projects/ missing project: frontmatter. Collision-prone filenames (Home.md, _index.md, index.md). Multiple notes with same prefix in a flat folder.

4. Naming Conventions

Every .md file should be:

• YYYY-MM-DD-topic.md (time-anchored) or topic.md / topic-subtopic.md (evergreen)
• Lowercase-hyphenated only

Flag: Spaces, CamelCase, uppercase (except README.md), generic names (notes.md, temp.md).

5. Frontmatter Validation (CRITICAL)

Every note (except README.md and agent/ running logs) MUST have YAML frontmatter:

---
date: YYYY-MM-DD
tags: [category, ...]
type: concept          # concept | decision | log | mission
status: active         # backlog | active | completed | archived
project: my-project    # required for notes in projects/
---

# Notes with type/status reported as "?" are missing frontmatter (or have malformed
# frontmatter the indexer couldn't parse).
vault query --type "?" --json
vault query --status "?" --json
# Fallback raw scan:
for f in $(find ~/obsidian_notes -name "*.md" -not -path "*/.obsidian/*" -not -path "*/.git/*"); do
    if ! head -1 "$f" | grep -q "^---"; then
        echo "MISSING FRONTMATTER: $f"
    fi
done

Flag: Missing frontmatter, missing date, empty tags, missing type or status. This was the #1 failure in stress testing — enforce strictly.

6. Wikilink Integrity

grep -roh '\[\[[^]]*\]\]' ~/obsidian_notes/ --include="*.md" | sort -u

For each wikilink, verify target exists. Classify as:

• Broken: Target doesn't exist and wasn't intentional
• Pending: Aspirational link to a note not yet created (acceptable)

Flag: Broken links. Also flag notes with ZERO outgoing wikilinks (orphan sources).

7. Orphaned Notes (Informational)

A note is orphaned if:

• Not linked FROM any other note
• Not a agent/ system file or README

This is a flag for review, NOT an automatic fix. Only add a link if there's a genuine conceptual connection. Standalone reference notes (especially in library/) are often legitimately orphaned — they're found by search, not by graph traversal. Do NOT add forced links just to pass the audit.

# Authoritative orphan list (built from the cached graph index):
vault orphans
# Use --json to feed into a hygiene script.

Flag: Orphaned notes that should be linked. inbox/ notes are exempt.

8. Content Quality

Read a sample of notes and check: reasoning present (WHY not just WHAT), tradeoffs documented, non-obvious insights (>5 min saved for future Claude), not a README restatement.

Flag: Notes that merely restate source material without adding reasoning or connections.

9. Note Size

find ~/obsidian_notes -name "*.md" -not -path "*/.obsidian/*" -not -path "*/.git/*" -exec wc -l {} + | sort -rn | head -10

• Target: 200-400 lines
• Flag: >800 lines (should be split)
• Flag: <10 lines (should be merged into another note)

10. Stale Content & Inbox Hygiene

Check agent/session-log.md (open items >2 weeks unresolved?), agent/open-questions.md (answered or no longer relevant?), inbox/ (items >2 weeks unprocessed?).

Flag: Stale open questions, unprocessed inbox items, outdated log entries.

11. Connection Quality

Read agent/connections.md:

• Are connections genuine cross-domain links (not forced)?
• Do they include confidence levels?
• Are any stale or invalidated?

12. Folder Depth

• Any depth is allowed (the vault tools handle it), but prefer 1-2 levels (projects/project/{logs,decisions,implementation,archive}/note.md)
• Flag: only structures that hurt legibility — e.g. a deep chain holding a single note

13. Volume Check

• 3-8 notes per project subfolder is healthy
• 1 note in a subfolder → should it just be in the parent?
• 15+ notes → should it be split into sub-topics?

14. CLAUDE.md / Rules Freshness

• Does ~/.claude/CLAUDE.md accurately reflect current vault structure?
• Does ~/.claude/rules/obsidian-notes.md match actual conventions being followed?
• Are any instructions stale or contradictory?

---

Report Format

## Vault Audit Report — YYYY-MM-DD

| # | Check | Status | Issues |
|---|-------|--------|--------|
| 1 | Sync Health | PASS/FAIL | ... |
| 2 | Folder Placement | PASS/WARN | ... |
| 3 | Subfolder Structure | PASS/FAIL | ... |
| 4 | Naming Conventions | PASS/WARN | ... |
| 5 | Frontmatter | PASS/FAIL | ... |
| 6 | Wikilink Integrity | PASS/WARN | N broken, M pending |
| 7 | Orphaned Notes | PASS/WARN | ... |
| 8 | Content Quality | PASS/WARN | ... |
| 9 | Note Size | PASS/WARN | ... |
| 10 | Stale Content | PASS/WARN | ... |
| 11 | Connection Quality | PASS/WARN | ... |
| 12 | Folder Depth | PASS/FAIL | ... |
| 13 | Volume | PASS/WARN | ... |
| 14 | Rules Freshness | PASS/WARN | ... |

**Score: X / 14**

### Action Items
1. [P0] Critical issue...
2. [P1] Important issue...
3. [P2] Nice-to-have...

---

Scoring Guide

• 12-14: Healthy vault, well-maintained
• 9-11: Good shape, minor cleanup needed
• 6-8: Significant gaps — fix before creating more notes
• Below 6: Instruction stack has systemic gaps — escalate to rules/skill updates