note-rename

name	note-rename
status	stable
description	Use when Obsidian vault notes have poor, generic, or uninformative filenames and need clear, descriptive names. Trigger phrases - "rename notes", "fix note names", "clean up filenames", "give notes better names". Also trigger for single notes - "rename this note", "give this a better name". Trigger when the user mentions "Untitled notes", "unnamed notes", or notes that are hard to find by name.

Note Rename

Give poorly named vault notes clear, descriptive filenames. Rename and fix backlinks. No sorting, no restructuring.

Principle: Core + Nahbereich + Report

• Core: Rename uninformative filenames, update backlinks across vault
• Nahbereich: Trash accidental notes via soft-delete (see rule below and references/trash-concept.md). Minimal YAML syntax repairs when already editing frontmatter. Syntactic fixes only — never add or change field values (that is property-enrich's job). Allowed repairs:
  • * → - in tag lists
  • Remove duplicate --- separators
  • Convert inline tags [X] to block format
  • Remove junk text before opening --- (e.g. dictation artifacts like Thx --- → ---)
  • Fix quoted keys with embedded colon: "type:" → type (the colon belongs to YAML syntax, not the key name)
  • Fill missing YAML created from the Source Hierarchy (filename date > Git first-commit > filesystem birthtime) before evaluating cooldown. See docs/metadata-requirements.md. This prevents birthtime corruption on subsequent skill runs.
  • Execution precedence: the quoted-key and duplicate---- repairs above are governed by Step 4a's sanity-check routing — apply them via references/yaml-edits.md recipe (f), which resolves duplicate-key collisions (identical → silent dedup; divergent → ABORT: skip + Class-A finding, no rename). Never hand-apply a key fix in a way that bypasses the recipe (f) Step 3 collision check.
• Report: Renames, backlink updates, 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, the skill auto-enriches created from the Source Hierarchy (filename date > Git first-commit > filesystem birthtime) before evaluating cooldown — see Nahbereich. Never use modification date.
clone_cluster_skip	true	When true (default), Step 4b SKIPs created enrichment for files whose only available date source is filesystem birthtime AND whose birthtime falls in a detected clone-cluster window. See references/clone-cluster-detection.md. The rename flow still runs (filename change applied), but the YAML created field is left absent (recoverable, not poisoned). Set to false to disable.
scope	inbox	Which folder to scan. inbox = inbox root only (default). inbox-tree = inbox folder including all subfolders (opt-in for bulk-mode, e.g. initial vault setup). vault = entire vault excluding root. folder:<path> = specific subfolder. User confirms before execution.

Scope Rules

• Vault root is always excluded unless the user explicitly asks to process root-level files. Root files are typically structural (OPS docs, config notes, plugin files) and rarely rename candidates.
• Folders starting with _ are excluded from scanning (_trash/, _secret/, _test-backup/).
• Folders starting with . are excluded (.trash/, .obsidian/).
• Template folders (e.g. 00_Templates) are excluded.

Protected Files

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

• _vault-autopilot.md in vault root
• Any file starting with _ in vault root (reserved for plugin management)

Rename Candidates

Rename notes with uninformative filenames: Untitled, Unbenannt, New Note, Draft, Blank note, Note from iPhone, Quick Note, URL-only names, hash-only names, obvious typos (95%+ clear intent).

Never rename: Already descriptive names.

Daily Notes (YYYY-MM-DD.md): Not automatically kept. Classify by content:

• Empty or boilerplate-only → Trash candidate (accidental note detection)
• Has content (links, text, ideas) → Rename candidate. Keep date prefix: YYYY-MM-DD - Context - Detail
• Multi-topic (links from different platforms, mixed themes) → TBD suffix. Flag for manual review.

Web captures: Apply prefix per references/web-capture-detection.md. Skip existing categorical prefixes.

Unclear cases: [Original Name] - TBD. When the original name contains a date, keep the date first: YYYY-MM-DD - TBD. The date must always lead for chronological sorting.

Accidental Note Detection (Nahbereich)

Soft-delete to _trash/ if ALL true: (1) generic filename, (2) no content beyond template boilerplate, (3) frontmatter has only generic tags and no real title. Add trash metadata per references/trash-concept.md. When in doubt → TBD prefix instead.

Daily Note Detection (Nahbereich)

Notes matching the Daily Note pattern (YYYY-MM-DD.md) get special handling. They are NOT auto-kept — classify by content (see Rename Candidates above). Location handling:

Detection rules:

1. Misplaced daily notes — YYYY-MM-DD.md outside the vault's canonical Daily Notes folder → move there first, then classify for rename like any other note. Add skill-log with Daily action for the move.
2. Hybrid names (YYYY-MM-DD Some Description.md) — this is NOT a daily note. It is a regular note with a date prefix. Process as a rename candidate — the date prefix is informative context, not a daily note pattern.
3. Future dates — if the note has a created date in frontmatter, use it as the correct date and rename accordingly. If a note with the corrected date already exists, resolve via naming (e.g. add a suffix). If no created date is available, flag for manual review. Always log the date correction in the skill-log action: Renamed from [original] (date corrected).
4. Already in correct Daily Notes folder — no move needed. Still classify for rename based on content.
5. Nested Daily Notes folders (e.g. inbox/Daily Notes/YYYY-MM-DD.md) — these are misplaced. The vault has ONE canonical Daily Notes folder. Move there, avoid duplicates.

Corrupted File Detection (Nahbereich)

Detect files with multiple YAML frontmatter blocks (two or more ---/--- pairs). This happens when two notes get accidentally merged — typically an append error during sync or import. These files cannot be reliably processed.

Action: Rename with a descriptive corruption label (e.g. YYYY-MM-DD - Korrupte Datei - Zwei Notizen verschmolzen). Write skill-log. Do not attempt to split the file — that requires manual review by the user.

Detection: Count --- pairs that enclose YAML-key-like content (at least one key: value line between the pair). Body-level --- horizontal-rule separators without YAML content do NOT count. Precise heuristic: see references/yaml-sanity.md Pattern 2. Two genuine frontmatter blocks = corrupted.

Sensitive Content Detection (Nahbereich)

Move to _secret/ if the note contains sensitive data: recovery phrases, API keys, passwords, tokens, or other credentials stored as plaintext. These notes are a security risk and must not remain in the vault unprotected. Add trash metadata with trash_source: note-rename and the original path. The _secret/ folder signals to the user that these files need manual review and secure handling — not just deletion.

Naming Rules

1. Capture core topic — scannable at a glance
2. Dash separator: Topic - Detail for two-level names
3. No filler words ("Note about", "Draft of")
4. Match content language
5. Max ~70 characters

Clusters: If 3+ notes share a topic, suggest a common prefix before renaming.

Context Segment

When renaming notes that have a date prefix, use a three-part name: YYYY-MM-DD - Context - Detail.

The Context segment answers: "What gives the reader the fastest orientation?" It can be:

• A platform (Instagram, YouTube, ChatGPT, Perplexity, Grok, GitHub, Reddit, LinkedIn)
• A project (the project or product name the note relates to)
• A life area (Family, Finance, Career, Health)
• An activity (Research, Interview, Meeting, Review)

Platform detection (when primary content is a link or capture):

URL Pattern	Context Segment
instagram.com	Instagram
youtube.com, youtu.be	YouTube
perplexity.ai	Perplexity
chatgpt.com	ChatGPT
grok.com	Grok
linkedin.com	LinkedIn
github.com	GitHub
reddit.com	Reddit
Other recognizable domain	Domain name (capitalized)

See also references/web-capture-detection.md for social platform detection rules.

Multiple links, same platform: One context segment. E.g. 3 Instagram links → still just "Instagram". Multiple links, different platforms: Use the dominant platform as context, or Research if no platform dominates. No links (pure text): Use project, life area, or activity as context.

Multi-Topic Rules

When a note covers multiple unrelated topics, join them with & in the Detail segment:

#	Topic Count	Platforms	Rule
1	1-2	any	All topics in the name with &
2	3-4	any	All topics in the name with & if it stays readable and under ~70 characters. Skill decides.
3	5-6	one dominant	All topics as keywords with &. One keyword per topic — enough to find the note later.
4	5+	multiple	YYYY-MM-DD - Mixed Content - Mixed Topics.md. Too chaotic for a meaningful name.
5	7+	any	YYYY-MM-DD - Mixed Content - Mixed Topics.md. Topic Override — content this fragmented cannot produce a meaningful name regardless of platform dominance.

Examples:

• 2 topics: 2025-12-03 - Instagram - HR Interview Tipps & SaaS.md
• 3 topics: 2025-12-04 - Instagram - SaaS & Dev Tools & Karpathy LLM.md
• 5-6 topics, one platform: 2025-12-11 - Instagram - Product & Interview & Claude & AI Cases & Cursor.md
• 5+ topics, multiple platforms: 2025-12-08 - Mixed Content - Mixed Topics.md
• 7+ topics, one platform: 2026-01-08 - Mixed Content - Mixed Topics.md (Topic Override — 7 topics, 93% Instagram, still too fragmented)

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 — Scan (step 2 below) and Check backlinks (step 6 below) 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 — registry state, folder topology, and birthtime clustering can change between invocations and previous results are not authoritative.

Workflow

1. Discover vault — resolve ${OBSIDIAN_VAULT_PATH}. Default scope: inbox root. Confirm with user.

2. Scan — list .md files.

3. Nahbereich — detect and trash accidental notes (soft-delete to _trash/). Move misplaced Daily Notes to the Daily Notes folder. Log each.

4. Classify — read title, tags, first ~30 lines (skip template boilerplate). For each note:

   • 4a. Repair corrupted quoted-key variants first (Nahbereich, sanity-check). Call references/yaml-sanity.md. Verdict-routing per references/yaml-sanity.md § "Per-skill policy":

     • BROKEN_KEYS_INSIDE_COLON (shape β — F26 inside-colon): normalize via references/yaml-edits.md recipe (f) — handles ALL quoted-key patterns, not just "created:"/"modified:" (broadened from v0.1.0/v0.1.2 hardcoded list). After normalization, resolve duplicate-key collisions per recipe (f) Step 3 (identical → silent dedup; divergent → ABORT, see next bullet). Re-call sanity-check (idempotent fixpoint) — verdict must now be OK, OK_QUOTED, or OK_NO_FRONTMATTER.
     • DUPLICATE_KEYS_IDENTICAL_VALUES (v0.1.4 W4): repair via recipe (f) silent dedup, then re-run sanity-check.
     • DUPLICATE_KEYS_DIVERGENT_VALUES (v0.1.4 W4 — F7 family): skip the file + log Class-A finding "duplicate-key-divergent-values". Do NOT rename — user may legitimately need to merge values first; rename would obscure the underlying ambiguity. Route to user.
     • MULTIPLE_FRONTMATTER_BLOCKS: use existing Corrupted File Detection (rename file with corruption-label).
     • OK_QUOTED: proceed normally.
     • OK / OK_NO_FRONTMATTER: proceed normally.

     YAML edits MUST follow references/yaml-edits.md (recipes b + f). Without this normalization a strict YAML parser cannot read the author-intended date, falls back to the Source Hierarchy → filesystem birthtime (often fresh on cloned vaults), and the cooldown evaluation in 4c silently skips legitimate candidates. Classification regex accepts both plain and standard-quoted forms. Historical bugs: repo issue #4 (2026-04-27) for created/modified; F26 cross-skill cluster (2026-04-28) generalized the inside-colon pattern; F7 (GR-3 Cell 1, 2026-05-01) generalized duplicate-key resolution beyond first-wins-silent (v0.1.4 W4).

   • 4b. After 4a, if YAML created is still missing: derive the value via Source Hierarchy Prio 1-3 first (filename > git, with German-date normalization in Prio 1 per references/german-date-normalization.md). If Prio 1-3 yields a value, write it to frontmatter (Nahbereich) and record the source. If Prio 1-3 yields no value, apply the clone-cluster gate per references/clone-cluster-detection.md: detect the vault-wide cluster window once per skill invocation, then invoke recipe (a) is_birthtime_in_clone_cluster_window. If recipe (a) returns 0 (in cluster) AND recipe (b) has_alternate_date_source returns 1 (no alt source), SKIP created enrichment for this note — do not write the field, log the file as Class-C "clone-cluster birthtime, no alt source" in the per-skill findings file, and store the current filesystem birthtime only for later restoration (rename-flow proceeds, but created stays absent). Otherwise (no cluster declared, or recipe (a) returns 1 = not in cluster), fall through to Prio 4 (filesystem birthtime) — write created from stat -f %SB / stat -c %W. Behavior gated by config clone_cluster_skip (default true); when false, the gate is a no-op and Prio 4 fires unconditionally.

   • 4c. Apply cooldown (per cooldown_days parameter) using the now-trustworthy created value. Cooldown-skipped notes are reported in the Skipped section of the report (not silently dropped) — see references/report-format-note-rename.md.

   • 4d. Mark as: rename, keep, or TBD.

5. Detect clusters — 3+ candidates on same topic → prepare prefix suggestion.

6. Check backlinks — find all [[Old Name]] references across vault.

7. Preview and confirm — show the preview table (see references/report-format-note-rename.md for format and bilingual templates). Match the language the user is speaking. Include a rationale section below the table explaining non-trivial decisions. Do not execute until the user explicitly confirms.

8. Execute — rename files, update all [[Old Name]] and [[Old Name| references.

9. Skill Log — for every processed note (renamed, reviewed, or trashed), write the skill log. See references/skill-log.md for the full spec. YAML tag-list edits and skill-log callout edits MUST follow references/yaml-edits.md (recipes d + e). After writing tag/callout, restore filesystem birthtime from the YAML created value read during classification. Use touch -t (see references/skill-log.md § Birthtime Preservation). After auto-enrich in step 4, YAML created is almost always available. Restore birthtime from it. In the rare case that auto-enrich found no source (no filename date, no Git, no readable birthtime), restore from the pre-write filesystem birthtime captured in step 4.

   Tag (idempotent):

   • Check if VaultAutopilot already exists in the tags list in YAML frontmatter.
   • If missing: add it. If present: do nothing. Never duplicate.
   • If no tags field exists: create one with VaultAutopilot as the first entry.

   Callout (append-only):

   • Check if > [!info] Vault Autopilot exists at the end of the note.
   • If missing: create the full callout block:

     > [!info] Vault Autopilot
     >
     > | Date | Skill | Action |
     > |------|-------|--------|
     > | YYYY-MM-DD | note-rename | [action] |
     

   • If present: append only a new > | YYYY-MM-DD | note-rename | [action] | row to the existing table. Never create a second callout.
   • Ensure one blank line separates the callout from the preceding content.

   Action types:

   • Renamed: Renamed from [old filename without .md]
   • Reviewed (name was already good): Reviewed — name already descriptive
   • Trashed (Nahbereich): Trashed — accidental note (soft-delete to _trash/)
   • Secret (Nahbereich): Secret — sensitive content (moved to _secret/)
   • Daily (Nahbereich): Daily — moved to Daily Notes folder

10. 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-rename.md. Create the folder chain if missing. Never edit prior findings — append-only ledger.

11. Report and log — write summary, append to logs/run-history.md.

Report Format

See references/report-format-note-rename.md for the full preview table format (bilingual), report template, and action types for skill log.

Quality Check

• Renamed files exist at new paths
• All backlinks updated (no broken [[]])
• No Daily Notes renamed
• User confirmed before execution
• Every processed file has VaultAutopilot tag in frontmatter (exactly once)
• Every processed file has skill log callout at the end
• Reviewed notes have "Reviewed" action, not "Renamed"
• Re-renamed notes have multiple callout rows, not multiple callouts
• Sanity-check called Step 4a per references/yaml-sanity.md (broadened from hardcoded "created:"/"modified:" to all quoted-keys)
• Quoted-key broken-key variants (shape β — inside-colon) normalized via recipe (f); standard quoted-keys (shape α) pass through as OK_QUOTED
• Duplicate-key divergent-value collisions (F7 family) skip + Class-A finding; file is NOT renamed — user merges manually first (v0.1.4 W4)