note-quality-check

Note Quality Check

Review vault notes by age, content quality, and relevance. Walk the user through decisions in small batches. Conservative — the skill never recommends trashing a note. Only the user decides what goes.

Principle: Core + Nahbereich + Report

• Core: Score notes, present clusters, walk user through decisions
• Nahbereich: Detect 0-byte files (permanent-delete candidates) and whitespace-only files (soft-delete candidates, see references/trash-concept.md). Candidates only — no destructive action happens before the preview (see Destruction Gate below).
• Report: Quality distribution, actions taken, parked items, findings for other skills

Parameters

Parameter	Default	Description
cooldown_days	3	Skip notes created within the last N days. Grace period so the user can review recent captures before automation touches them. Date source: YAML created field in frontmatter. If missing, evaluate via the Source Hierarchy (filename date > Git first-commit > filesystem birthtime, gated by the clone-cluster check) — read-only; this skill does not write created (property-enrich's job). Never use modification date.
clone_cluster_skip	true	When true (default), age/cooldown evaluation DEFERs for files whose only available date source is filesystem birthtime AND whose birthtime falls in a detected clone-cluster window (age undecidable — flag, do not score staleness). See references/clone-cluster-detection.md. Set to false to fall through to filesystem birthtime.
scope	inbox	Which folder to scan. inbox = inbox only. vault = entire vault. User confirms before execution.
batch_size	5	Number of notes to present per round. User decides before next round continues.

Protected Files and Folders

Never process or score these (see references/vault-autopilot-note.md):

• _vault-autopilot.md in vault root
• Any file starting with _ in vault root (reserved for plugin management)
• Everything inside _trash/ (see references/trash-concept.md)

Destruction Gate

No destructive action happens before the preview. Phase 1 only detects Nahbereich candidates (0-byte, whitespace-only); the preview presents them as the first decision block of the walk-through, and only an explicit user confirmation executes them. This applies to every destructive path of this skill: permanent delete (0-byte), soft-delete to _trash/, and archive moves.

Behavior change (2026-06-11, deliberate): earlier versions executed 0-byte deletes and whitespace-only trashes during the scan, before the user saw anything. That violated the "AI recommends, human decides" principle and the README approval promise. The order is now: detect → preview → confirm → execute.

Four Actions

Every note gets exactly one action, chosen by the user:

Action	What happens	When to suggest
Keep	Note stays. Optionally suggest a better target folder.	Note has clear purpose or reference value
Archive	Move to archive folder (e.g. 099_Archive/)	Completed projects, past events, historical reference
Park	No action now. Tracked in report for later review.	User is unsure, needs more context, or wants to revisit
Trash	Soft-delete to _trash/ with metadata	Only when user explicitly chooses this

The Golden Rule: Never Recommend Trash

The skill does not say "delete this" or "trash this". Instead:

• For notes the skill does not understand: "I cannot determine the purpose of this note. What is it for?"
• For notes with weak signals: suggest Keep or Archive, not Trash
• Only the user can say "Trash"

Intentional Content Signals

A note is considered intentional (and never a Nahbereich candidate) if ANY of these are true:

1. Contains an embed (![[...]])
2. Contains a wikilink ([[...]])
3. Has YAML frontmatter with meaningful values (title, tags, description)
4. Has 3+ lines of non-whitespace content
5. Has a descriptive filename (not generic like "Untitled" or "New Note")

Fail-safe default: any uncertainty in the signal evaluation → KEEP/DEFER, never auto-trash. One ambiguous signal is enough to keep a note out of the Nahbereich set — deleting a valuable note is the worst failure class this skill has, strictly worse than leaving a worthless note in place. Only literally-empty content (0 bytes, pure whitespace) is ever a candidate.

Quality Criteria

Evaluate each note against all five. These inform the suggested action (Keep vs. Archive), not a delete decision.

#	Criterion	Signal
1	Staleness	>12 months old, no edits in 6+ months
2	Obsolete	Past events, completed projects, expired offers
3	Low substance	1-2 sentences, URL-only, undeveloped thought
4	Redundancy	Near-duplicate title and opening lines in same folder
5	No clear purpose	No action, no reference value, no idea worth keeping

TBD - prefixed notes (from note-rename) count as one pre-existing signal.

Age Detection

1. YAML frontmatter (created, date, modified) — authoritative
2. Source Hierarchy fallback (read-only): filename date > Git first-commit > filesystem birthtime — birthtime only via the clone-cluster gate per references/clone-cluster-detection.md. If the note's birthtime falls in a detected clone-cluster window and no alternate source exists, age is undecidable: DEFER staleness scoring for that note, flag "age uncertain (clone-cluster)" in the findings file, and never count uncertain age toward an Archive suggestion. (Clone-time birthtimes are empirically unreliable — the F3/GR-3 class: 36.8% of files in a robocopy clone clustered at clone time.)
3. Bulk-import: Many files sharing same creation timestamp — flag age as uncertain. Report, do not modify frontmatter (property-enrich's job).

Pre-flight

Before every invocation of this skill — including resumed sessions and re-triggers within the same conversation:

1. Always (every OS): Run references/clone-preflight.md. It detects clone-induced birthtime clusters and emits a WARN before any date-derivation runs. Cross-platform — applies on macOS, Linux, and Windows. WARN-flow only; skill execution continues.
2. On Windows additionally: Follow references/windows-preflight.md end-to-end (registry check, trailing-dot folder detection, Windows-aware file-enumeration pattern). The enumeration pattern in Step 6 of that preflight applies to every subsequent file-listing call this skill makes — the scan in Phase 1 included. On macOS or Linux, this preflight is a no-op.

Run the checks freshly each time. Do not assume a previous turn's pass result still holds.

Workflow

Phase 1: Discover and Scan (read-only)

1. Resolve ${OBSIDIAN_VAULT_PATH}. Ask for target folder. Non-recursive default.
2. Confirm scope if 50+ notes.
3. Sanity-check per note. Call references/yaml-sanity.md before reading any frontmatter. Verdict-routing per § "Per-skill policy" — this skill never repairs YAML:
   • BROKEN_KEYS_INSIDE_COLON, DUPLICATE_KEYS_DIVERGENT_VALUES, DUPLICATE_KEYS_IDENTICAL_VALUES, MULTIPLE_FRONTMATTER_BLOCKS, UNCLOSED_FRONTMATTER: exclude the note from scoring + finding (Class-A for divergent/multi-block/unclosed, Class-C otherwise; route to property-enrich / note-rename). A corrupted file is a repair case, not a low-quality note — broken YAML must never feed the quality criteria or end up as a trash suggestion.
   • OK / OK_QUOTED / OK_NO_FRONTMATTER: proceed normally (regexes accept plain and standard-quoted forms).
4. Read all notes: title, frontmatter, first ~30 lines, file metadata. Apply cooldown + age detection per the Age Detection rules (clone-cluster DEFER included).
5. Nahbereich detection (no execution): collect 0-byte files as permanent-delete candidates and whitespace-only files as soft-delete candidates. Do NOT delete or move anything in this phase — see Destruction Gate.

Phase 2: Cluster and Group

6. Detect clusters using (in order):
   • Filename prefix matching (e.g., MB -, CREALOGIX, ITG -)
   • Tag overlap (3+ shared tags between notes)
   • Semantic grouping for remaining unclustered notes
7. Assign unclustered notes to a "Mixed" group.
8. Order clusters: largest first, then alphabetical.

Phase 3: Walk-Through

9. Nahbereich candidates first. Present the collected 0-byte and whitespace-only candidates as the opening decision block (same table format, suggested action prefilled). Wait for user confirmation; execute only what the user approves.
10. Present one cluster at a time. Use this exact format:

**Cluster X: "[Name]" (N Notes)**
Context: [1-line description of what connects these notes]

| # | Note | Type | Lines | Suggested Action |
|---|------|------|------:|-----------------|
| 1 | Example Note.md | Brief Draft | 68 | Archive (A) |
| 2 | Another Note.md | Project Doc | 115 | Keep (K) |

**Actions:**
- **Keep (K)** — stays where it is, optional folder suggestion
- **Archive (A)** — moves to `099_Archive/[Cluster]/`
- **Park (P)** — no action now, recorded in the report for later
- **Trash (T)** — soft-delete to `_trash/` (recoverable)

Examples: `1A 2K` or `all A` or `1-5 A, 6T`

→ Your decision?

11. Show max batch_size notes per table (default 5). If a cluster has more, continue with a second table after the user decides.
12. Wait for user decisions. Accept shorthand (e.g. 1A 2A 3K) or cluster-wide (e.g. alle A).
13. Execute actions immediately after each round (move files, add trash metadata). Trash metadata fields MUST be written per references/yaml-edits.md recipes (b/c) — never str.replace, never multi-line regex; see references/trash-concept.md for the field set.
14. Skill Log — for each actioned file: add VaultAutopilot tag and append skill log callout row (see references/skill-log.md). YAML tag-list edits and skill-log callout edits MUST follow references/yaml-edits.md (recipes d + e).
15. Continue to next round or next cluster.

Phase 4: Report

16. Write findings file — for any non-trivial Findings (Class A/B/C/D as defined in references/findings-file.md), append a section to <VAULT>/_vault-autopilot/findings/<YYYY-MM-DD>-note-quality-check.md. Create the folder chain if missing. Never edit prior findings — append-only ledger.
17. Write summary report. Append to logs/run-history.md.

Report Format

## Note Quality Check Report — [Date]

### Done
- Analyzed: X | Kept: X | Archived: X | Trashed: X | Parked: X
- Nahbereich (user-approved): X files removed (0-byte: X, whitespace-only trashed: X)

### Skipped
- Cooldown: X | Age undecidable (clone-cluster): X | Broken YAML (excluded from scoring): X | Protected: X

### Parked (revisit later)
- [List of parked notes with 1-line context each]

### Clusters Reviewed
- [Cluster name]: X notes — [actions summary]

### Findings
- Uncertain age (import suspected): X notes
- [Observations for other skills]

Quality Check

• Every action was chosen by the user (no auto-trash of content notes)
• No destructive action executed before the preview (Destruction Gate held — detect → preview → confirm → execute)
• Nahbereich limited to 0-byte and whitespace-only files; any intentional signal kept the note out (KEEP/DEFER on uncertainty)
• Sanity-check called before frontmatter reads; broken-YAML notes excluded from scoring with finding, never scored or trash-suggested
• Age/cooldown evaluated via Source Hierarchy with clone-cluster gate — uncertain age flagged, never counted toward Archive
• Trash metadata and skill-log edits used references/yaml-edits.md recipes (b/c fields, d/e tag + callout)
• Parked notes are listed in report
• Uncertain-age notes reported, not modified
• Findings file written per references/findings-file.md for any non-trivial findings