Vault Health Feedback

vault-health-feedback

Constraints

• NEVER scan whole vault; sample strategically
• NEVER give more than 3 recommendations
• Check layers in order: workflow -> cognitive -> structural
• NEVER equate structural mess with system failure (check workflow first)
• NEVER repair, move, or restructure without explicit confirmation

Trigger Boundary

Use when: vault feels archival, knowledge not returning, system health diagnosis needed, highest-leverage repair unclear, user says "vault is dead" or "nothing comes back."

Do NOT use for:

• Inbox routing -> inbox-triage
• Recent-note relationships -> connection-review
• Week-level synthesis -> weekly-synthesis
• Direct restructuring before diagnosis
• Promoting material -> note-promotion

Boundaries

• Owns: workflow health diagnosis, cognitive return assessment, structural friction detection
• Delegates to: inbox-triage (root cause is inbox backlog), opencode-context-maintenance (root cause is context drift)
• Never absorbs: inbox routing, relationship analysis, synthesis, promotion, direct restructuring

Continuations

| Condition | Next skill | |-----------|-----------| | Root cause is inbox backlog | inbox-triage | | Root cause is context drift | opencode-context-maintenance | | Vault paths inaccessible, possible config issue | opencode-context-maintenance | | Vault is deeply archival, needs structural redesign | Escalate to human |

Companion Skill

All vault operations follow obsidian-mcp. Forbidden: obsidian_patch_note, obsidian_append_to_note. Verify every write through readback.

Procedure

Phase 1: Workflow Layer (always check first)

When assessing health metrics, read references/examples.md.

1. obsidian_list_notes path:"Inbox/" -> inbox freshness (items, age)
2. obsidian_search_notes query:"type: synthesis" -> synthesis frequency
3. Check for recent triage/review/promotion activity
4. Score: active / stale / dead

Phase 2: Cognitive Layer (only if workflow is active or stale)

1. Sample 5-10 recent notes for reuse signals (links back, references)
2. Check if themes recur across time windows
3. Look for notes that were never revisited after creation
4. Score: returning value / flat / declining

Phase 3: Structural Layer (only if cognitive layer shows issues)

1. Check for orphan zones, hollow clusters, tag noise
2. Identify fragmentation patterns
3. Score: clean / messy but functional / blocking workflow

Phase 4: Recommend

When formatting diagnosis, read references/templates.md.

1-3 highest-leverage interventions, ranked. Report what NOT to do now.

Health Metrics Thresholds (expand for quantitative reference)

Workflow layer:

• Inbox items >30 days old = stale signal
• Synthesis frequency 40% unlinked notes = structural concern
• Tag entropy >50 tags with 4 with declining cognitive > structural blocking
• Stale workflow > flat cognitive > messy structural
• Active workflow with messy structure = healthy (do not intervene)

Gotchas

Gotcha 1: Starting from structure

What happens: Agent counts orphans and messy folders first Why it is wrong: Structural mess may be irrelevant if workflow is healthy Correct approach: Always check workflow -> cognitive -> structural in order

Gotcha 2: Too many recommendations

What happens: Agent gives 5-7 improvement suggestions Why it is wrong: No execution focus; user is overwhelmed Correct approach: Maximum 3 interventions, ranked by leverage

Gotcha 3: Diagnosis becomes cleanup

What happens: Agent starts moving/renaming/restructuring during diagnosis Why it is wrong: Unauthorized modification; diagnosis should inform, not act Correct approach: Report findings, recommend interventions, wait for confirmation

Validators (CI only, not runtime)

• validators/pre-check.sh: Confirms vault is accessible for sampling
• validators/post-check.sh: Verifies cognitive -> structural)
• No repair executed without confirmation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: r007b34r
• Source: r007b34r/opencode-obsidian-knowledge-workflow
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.