Unreal Obsidian Vault Update

UE5 Obsidian Vault — Full Pipeline

Vault location: ~/Documents/Unreal-Engine-Obsidian/ GitHub repo: <your-github-username>/Unreal-Engine-Obsidian Skill: unreal-obsidian-vault-update

When to use

Adding new tutorial content, architecture docs, or making structural changes to the vault.

Pipeline (5 phases)

Phase 1: Research

1. Identify topic gaps — scan existing tags/folders to find what's missing
2. Search YouTube for quality tutorials on those topics
3. Verify UE5 version relevance (target 5.6/5.7, reject older deprecated content)
4. Compile a candidate video list with URLs, titles, channels, durations

Phase 2: Extract

1. For each video, try youtube-transcript-api first for raw transcripts
2. Fall back to web_extract on YouTube URL
3. Fall back to web_search for companion written content
4. Save each file to the appropriate folder with frontmatter

Critical pitfall: Subagent write_file writes to sandbox, NOT the real filesystem. Files appear to succeed but don't persist. Fix: Use terminal() for file writes from subagents, or do writes from the main session directly.

Phase 3: Format

For each new folder:

1. Add consistent YAML frontmatter to all files:

   ---
   title: "Video Title"
   source: "https://www.youtube.com/watch?v=VIDEO_ID"
   video_id: "VIDEO_ID"
   type: "youtube-summary"
   series: "Series Name"
   episode: N
   tags: [ue5, topic1, topic2]
   ---
   

2. Add ## Related section with wikilinks:
   • ← Previous: [[filename]]
   • → Next: [[filename]]
   • 📚 Series: [[_MOC_FolderName]]
3. Create _MOC_FolderName.md index file linking all files in the folder

Phase 4: Review (3-reviewer gate)

MANDATORY before any push. Three independent reviews:

1. Self review — file-by-file sweep checking for duplicates, content quality, format consistency
2. Profile review 1 (e.g., Architect) — independent verification of duplicates, content quality, UE5 version compatibility
3. Profile review 2 (e.g., Secretary) — wikilink validation, MOC completeness, review doc accuracy

Fix all issues found before proceeding. If any reviewer flags a FAIL, resolve and re-review.

Phase 5: Release

1. Update README.md — ensure the folder tables, file counts, and version links match current vault state
2. Update CHANGELOG.md with new version section at the TOP:

   ## [vX.Y.Z] — YYYY-MM-DD
   
   ### Added
   - Description of new files/folders
   
   ### Fixed
   - Description of fixes
   

3. Commit: git add -A && git commit -m "vX.Y.Z — brief description"
4. Pull and push: git pull origin main --rebase && git push
5. Create GitHub release:

   gh release create vX.Y.Z --title "vX.Y.Z — Short Title" --notes "## What's New
   
   Human-readable summary of changes.
   
   **Vault total: N files across M folders**"
   

Version numbering

• Major (X): Major restructure, breaking changes
• Minor (Y): New topic folders or significant new content
• Patch (Z): Fixes, small additions, formatting

Workflow B: Merge external PR + apply errata fixes

When a community contributor submits a PR that also flags issues in existing vault content:

1. Review the PR — check gh pr view <N> --json body,files,additions,deletions,mergeable
2. Check for errata — read the errata/alignment file from the PR branch (use gh api on the fork's branch ref)
3. Merge the PR — gh pr merge <N> --repo <repo> --merge then git pull
4. Apply ALL fixes from the errata — do NOT stop after merging. The PR documents issues but does NOT fix them in your files. You must apply each fix yourself.
5. Update README.md — add new folders/files to the appropriate tables
6. Update CHANGELOG.md — new version entry with both "Added" (PR content) and "Fixed" (errata corrections) sections
7. Also update any stale references in prior CHANGELOG entries — e.g., if the errata replaces "INI setup" with "module registration", the v1.3.0 entry that says "INI setup" should be updated too
8. Commit, push, and create GitHub release (Phase 5 steps)

Critical: Merging a PR and fixing the issues it flags are TWO SEPARATE STEPS. Never assume the PR fixes its own findings.

Pitfalls

• Always git pull --rebase before push — remote may have changes from other sessions
• Update CHANGELOG.md BEFORE committing
• Release notes should be human-readable — explain what's useful, not commit messages
• Credential helper: gh auth git-credential is global default. No keychain prompts.
• Subagent file writes — see Phase 2 pitfall above
• stat -f '%z' fails with # in filenames — use os.path.getsize() in Python
• Forgetting README + CHANGELOG after content changes — any merge, fix, or content addition that changes the vault structure MUST update both. The user will call it out. Make it automatic: after every git pull that adds folders, immediately update README tables + CHANGELOG entry before committing.
• GitHub Release is part of the workflow — user preference is versioned releases (CHANGELOG + GitHub Release). Don't skip the gh release create step.
• Verify the vault path before trusting this skill's hardcoded value. The REAL git clone is ~/Documents/Unreal-Engine-Obsidian (has .git, 250+ notes, primary working copy). ~/Unreal-Engine-Obsidian is an EMPTY shell (.obsidian/ only, no .git) — editing there writes into a void. Always cd/stat the actual path first; do not assume the documented path is right, and update this skill if it drifts again.
• Obsidian app points at the wrong (empty) vault? Repoint, don't symlink. If ~/Unreal-Engine-Obsidian opens empty in Obsidian while the real clone is at ~/Documents/Unreal-Engine-Obsidian, fix the app's vault registration, not the filesystem: back up then edit ~/Library/Application Support/obsidian/obsidian.json, finding the vault entry whose path is the empty folder and rewriting path to the real one. Both vaults are usually already registered (different IDs) — you only need to repoint one. Non-destructive; the empty folder becomes orphaned and safe to delete. Verify with python3 -c "import json;json.load(open(...))['vaults']" after editing.
• Never let a release task run from a duplicate/orphan chain. When driving the pipeline through Kanban, a stray duplicate task (e.g. from a re-run create) can reach a release: step and push a premature tag/commit before the real chain finishes. Gate every release task behind its true parent, and before running it confirm no orphan already pushed the version tag (git tag -l vX.Y.Z, gh release list). If a premature release exists, delete the tag + GitHub release and reconcile before the real release runs.