Vault Review

Vault Review

Overview

Discipline skill that builds a composite review queue ranking notes by: days since last review (last_reviewed frontmatter), backlink density (notes with zero outlinks score highest), maturity stage (maturity frontmatter: seedling > sapling > tree > ancient-tree), and linked-note recency (notes connected to recently modified notes surface first). Surfaces 5-10 notes per session. Updates last_reviewed frontmatter on completion. Dispatches moc-gap-detector to surface structural gaps alongside the review.

When to Use

• Starting a review session.
• Checking which permanent notes need attention.
• Running the daily/weekly/monthly review ritual.

When NOT to use

• For vault maintenance (orphans, broken links, stale sweeps) — use vault-health.
• For processing new notes into atomic form — use process-notes.
• For quick single-note review without the queue system — just Read and Edit directly.

Constants

• QUEUESIZEDAILY: 5
• QUEUESIZEWEEKLY: 10
• QUEUESIZEMONTHLY: 15
• QUEUESIZESMART: 10
• SCORE_CAP: 20
• ORPHAN_PENALTY: 10
• NEVERREVIEWEDDAYS: 365
• TASK_DIR: .mz/task/

Core Process

| Phase | Goal | Details | | ----- | --------------------- | -------------------------- | | 0 | Setup | Inline below | | 1 | Score & Queue | phases/score.md | | 1.5 | User approval — queue | Inline below | | 2 | Review session | phases/review_session.md |

Phase 0: Setup

1. Resolve vault path from $ARGUMENTS, then OBSIDIAN_VAULT_PATH env, then MZ_VAULT_PATH env. If none resolve, ask the user via AskUserQuestion — never guess.
2. Detect review mode: if $ARGUMENTS contains daily, weekly, or monthly, use that mode. Otherwise use smart.
3. task_name = _vault-review_ where ` is today's date (underscores) and is the resolved review mode; on same-day collision append v2, v3`.
4. Create TASK_DIR/.
5. Write state.md with schema_version: 2, phase_complete: false, what_remains: [], Status: running, Phase: 0, Started: , Vault: , Mode: .

Phase 1.5: User approval — Review Queue

This orchestrator (not a subagent) presents this gate. This step is interactive and must not be delegated.

Pre-read: Read .mz/task//review_queue.md in full and capture its contents into context.

Surface 1 — emit the plan message. Output the artifact verbatim as a normal markdown chat message:

## Review queue ready for review — vault-review

/review_queue.md>

MOC gaps detected:  — details in .mz/task//moc_gaps.md

---
**Approve** → proceed to Phase 2 (review session)  ·  **Reject** → mark task aborted, no notes updated  ·  reply with feedback to revise

Emit the full verbatim contents of .mz/task//review_queue.md — do not substitute a path, summary, or placeholder.

Surface 2 — call AskUserQuestion. A short selector — do not re-embed the artifact in the question body:

• question: The review queue above is ready for review.
• options: Approve — proceed to Phase 2 (review session) · Reject — mark task aborted, no notes updated

Response handling:

• Approve → update state to queue_approved, proceed to Phase 2.
• Reject → update state to aborted_by_user and stop. Do not proceed.
• Any other reply (feedback) → adjust queue parameters (exclude a folder, change weights, filter by maturity, resize), re-run Phase 1 if needed, overwrite review_queue.md, return to Surface 1, re-read the updated artifact, and re-emit the entire plan message from scratch. This is a loop — repeat until the user explicitly approves. Never proceed to Phase 2 without explicit approval.

Techniques

Techniques: delegated to phase files — see Phase Overview table above.

Common Rationalizations

| Rationalization | Rebuttal | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "I know which notes need review, skip the queue." | "Interest-driven review creates survivorship bias — the notes you remember are already linked; the queue surfaces the orphaned ideas that have never found a connection." | | "Update last_reviewed manually later." | "Manual timestamp updates are skipped 80% of the time; without accurate last_reviewed data the queue degrades into random selection." | | "Skip the MOC gap detection, just do the review." | "MOC gaps and review needs are correlated — a cluster of seedling notes all lacking a MOC is exactly the pattern vault-review is designed to surface." |

Red Flags

• Starting a review without showing the queue first — a hidden queue means the user cannot redirect.
• Marking notes as reviewed without the user confirming they were actually read.
• Reviewing notes in a fixed order (alphabetical, recency) instead of composite scoring.
• Proceeding to Phase 2 without explicit "approve" from the user.

Verification

Print this block before concluding — silent checks get skipped:

vault-review verification:
  [ ] Ranked queue emitted verbatim as a chat message (Surface 1) and AskUserQuestion selector presented before session started
  [ ] `last_reviewed` updated only for notes the user confirmed reviewing
  [ ] MOC gaps surfaced alongside the queue (from moc-gap-detector)
  [ ] state.md Status is `completed` with Completed timestamp

If any box is unchecked, the skill did not run correctly — report the failure explicitly rather than claiming success.

State Management

State persists to .mz/task//state.md. Schema is v2: the file's first line is schema_version: 2, and alongside the skill's existing Status / Phase / Started keys it carries phase_complete (boolean) and what_remains (YAML list of strings). Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass; refresh what_remains on every phase transition; what_remains MUST be [] when Status: complete. On reading a schema_version: 1 or unversioned file, add the missing keys, set schema_version: 2, and log the upgrade.

Error Handling

• Vault path missing or invalid → escalate via AskUserQuestion; never guess a default.
• Zero permanent notes found (empty glob) → escalate via AskUserQuestion with the scanned folder path; the vault layout may differ from the default convention.
• moc-gap-detector returns empty or malformed → retry the dispatch once; if still empty, note the gap in state.md and continue the review session without MOC gap data.
• All notes have identical scores (degenerate queue) → fall back to recency sort and note the degenerate condition in state.md.

Source & license

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

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

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