Vault Schema Refactoring Log

Template Overview

As a personal knowledge vault expands beyond thousands of notes, legacy frontmatter conventions, inconsistent tag names (#deepwork vs #deep-work), and deprecated folder schemas create cognitive friction. Performing bulk find-and-replace operations without an auditable plan risks corrupting YAML frontmatter and breaking wikilinks. The Vault Schema Refactoring Log provides an engineering-grade migration plan to stage, test, execute, and verify large-scale vault schema changes.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "Vault Refactor: [Refactoring Initiative / Schema vX.Y]"
date_executed: [YYYY-MM-DD]
vault_architect: "[[Your Name]]"
target_files_count: [Number]
backup_archive_path: "/backups/vault_backup_[YYYYMMDD].tar.gz"
git_branch_name: "refactor/yaml-frontmatter-v2"
tags: [pkm, vault-maintenance, refactoring, yaml, taxonomy, migration]
---

# Vault Schema Refactoring Log — [Refactoring Initiative]

## 1. Refactoring Objective & Problem Statement
- **The Problem:** Inconsistent frontmatter keys across 450 legacy notes (some use `tags:`, others use `tag:`; some use `author:`, others use `created_by:`).
- **The Target State:** Standardize all notes on strict YAML schema: `tags:` as an array, `created:` in ISO-8601 `YYYY-MM-DD`, and `type:` matching the official taxonomy.
- **Rollback Safety Guardrail:** Full compressed tarball archive created and verified before executing any batch scripts.

## 2. Pre-Flight Safety & Backup Verification
```bash
# 1. Create full uncompressed Git snapshot and tarball backup
cd ~/Documents/PersonalVault
git add -A && git commit -m "pre-refactor: snapshot before schema migration"
tar -czvf ~/backups/vault_backup_$(date +%Y%m%d).tar.gz .
echo "Backup verified: $(ls -lh ~/backups/vault_backup_*.tar.gz | tail -n 1)"

3. Transformation Rules & Migration Scripts

Target Element	Legacy Pattern (Before)	Canonical Pattern (After)	Tool / Command Executed
Tag Consolidation	#deepwork, #deep_work	#deep-work	Python regex script in virtualenv
Frontmatter Key	author: [[Name]]	author: "[[Name]]" (Quoted)	YAML lint script
Date Format	date: 10/09/26	date: 2026-10-09	ISO-8601 normalization script

4. Execution Terminal Log & Validation

# Dry run test on 5 sample files
python3 scripts/migrate_frontmatter.py --dry-run --dir ./notes/

# Execute batch migration across all 450 files
python3 scripts/migrate_frontmatter.py --execute --dir ./notes/

# Verify zero git syntax corruptions via linter
pnpm yaml-lint ./notes/**/*.md

5. Post-Migration Verification & Graph Health

• Obsidian graph reloaded; zero broken backlink warnings.
• Full-text search queries execute cleanly without parsing errors.
• Git diff inspected across 20 randomly sampled files; changes match migration spec.
• Changes merged to main branch: git checkout main && git merge refactor/yaml-frontmatter-v2.

## Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

```markdown
---
title: "Vault Refactor: ISO Date Normalization"
date_executed: 2026-10-09
vault_architect: "[[Julian Thorne]]"
target_files_count: 240
backup_archive_path: "/backups/vault_pre_iso_20261009.tar.gz"
git_branch_name: "refactor/iso-dates"
tags: [pkm, vault-maintenance, refactoring, yaml, taxonomy, migration]
---

# Vault Schema Refactoring Log — ISO Date Normalization

## 1. Summary
Migrated 240 template files to enforce strict `YYYY-MM-DD` frontmatter dates for 100% compliance with SEO Gate 22 (zero hard-coded stale year dates in page titles).

## 2. Execution
- Ran Python script across `src/content/templates/`.
- Verified clean build with `pnpm build && pnpm gates`.

When to Use and When to Avoid

When to Use

• Use before executing batch regex replacements, Python migrations, or mass renames across your Markdown vault.
• Use to preserve an audit log of what script was run and how to revert in the event of YAML corruption.
• Use when updating your personal knowledge management taxonomy to a new version.

When to Avoid

• Avoid using when manually editing a single individual note.
• Avoid using without taking a verified backup first.

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Analyze the vault schema refactoring log:
1. Verify the regex and bash commands for edge cases that could accidentally delete or corrupt YAML frontmatter.
2. Check that the backup and rollback sequence is airtight and fail-safe.
3. Formulate a Python dry-run script snippet to validate the migration before modifying files.
Output in structured Markdown.

Your data remains securely on your Mac with zero cloud exposure.