# Vault Review

> ALWAYS invoke when starting a knowledge review session, surfacing notes to review, checking which notes are due for review, or running the weekly/monthly review ritual.

- **Type:** Skill
- **Install:** `agentstack add skill-doctormozg-claude-pipelines-vault-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DoctorMozg](https://agentstack.voostack.com/s/doctormozg)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DoctorMozg](https://github.com/DoctorMozg)
- **Source:** https://github.com/DoctorMozg/claude-pipelines/tree/master/plugins/mz-knowledge/skills/vault-review

## Install

```sh
agentstack add skill-doctormozg-claude-pipelines-vault-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

- **QUEUE_SIZE_DAILY**: 5
- **QUEUE_SIZE_WEEKLY**: 10
- **QUEUE_SIZE_MONTHLY**: 15
- **QUEUE_SIZE_SMART**: 10
- **SCORE_CAP**: 20
- **ORPHAN_PENALTY**: 10
- **NEVER_REVIEWED_DAYS**: 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.
1. Detect review mode: if `$ARGUMENTS` contains `daily`, `weekly`, or `monthly`, use that mode. Otherwise use `smart`.
1. `task_name` = `_vault-review_` where `` is today's date (underscores) and `` is the resolved review mode; on same-day collision append `_v2`, `_v3`.
1. Create `TASK_DIR/`.
1. 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](https://github.com/DoctorMozg)
- **Source:** [DoctorMozg/claude-pipelines](https://github.com/DoctorMozg/claude-pipelines)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-doctormozg-claude-pipelines-vault-review
- Seller: https://agentstack.voostack.com/s/doctormozg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.