wiki-context/skill/compile.md

Compile Procedure

The compile operation reads recent vault changes, updates affected pages, refreshes landings and indexes, generates synthesis pages when warranted, and commits the result.

Pre-flight

1. Read <vault-root>/CLAUDE.md (the spec)
2. Read <vault-root>/log.md (find timestamp of last compile entry)
3. Confirm the vault is in a clean git state. If there are uncommitted changes:
   • If they are user edits in progress, stop and ask the user to commit or stash before proceeding
   • If they are leftovers from a failed prior run, stop and report — do not auto-clean

Step 1: Identify changes since last compile

• List all files in Sources/ with mtime newer than the last compile timestamp from log.md
• Read those files in full
• Categorize: new files, edited files
• For each, identify its type: (project-plan, session-notes) and domain from path: frontmatter (Dev, Venture, Homelab, Reference)
• Also check Wiki/ for any manual edits to entity or synthesis pages
• If a file has no frontmatter or invalid frontmatter, flag it but proceed with best-effort categorization

Step 2: Pre-compile commit

Make a single commit capturing the vault state before any writes:

git add -A
git commit -m "pre-compile: <reason>"

Where <reason> is the trigger phrase or a one-line summary of what's about to be processed (e.g., "compile run, 3 new sessions and 2 project edits").

Step 3: Update affected pages

For each project page touched by recent changes:

• Refresh the Current state section based on session notes added since the last update
• Add new session notes to the Sessions section as wikilinks
• Update Decisions locked if recent sessions captured new decisions
• Update Open questions based on recent activity
• Update the updated: frontmatter date

For each entity page referenced by recent changes:

• Update Current state if relevant
• Add new related projects/sessions to Related projects section
• Append a History entry if a significant event occurred
• Update the updated: frontmatter date

Step 4: Entity promotion check

For any topic referenced in 2+ projects or 3+ sessions that does not yet have an entity page, propose promotion:

• Add to a promotions: list in the compile summary
• Do not auto-create. The user reviews the proposed promotions and triggers a follow-up compile if any are approved.

(Exception: if the user's invocation explicitly authorized auto-promotion for this run, proceed and create the pages.)

Step 5: Synthesis check

Look for cross-cutting patterns warranting a synthesis page:

• Multiple sessions/projects converging on the same theme
• A pattern of decisions across projects that benefits from a unified statement
• A body of related entities that lacks a connecting page

If such a pattern is identified:

• Draft a synthesis page per the spec in CLAUDE.md
• Required: sources: frontmatter listing every page it pulls from
• Required: prose attribution for each substantive claim
• Required: explicit flag for any agent-inference claim not directly in a source

Do not generate synthesis pages aggressively. One per compile run is the norm; zero is fine. Three is suspicious.

Step 6: Refresh topic landings and indexes

For each domain with changes, update BOTH Sources and Wiki indexes:

Sources indexes (Sources/<domain>/index.md):

• Regenerate Active projects list from frontmatter query
• Regenerate Recent sessions list (last 10 or last 30 days)
• Update Completed projects section
• Update updated: date

Wiki indexes (Wiki/<domain>/index.md):

• Update Entities list if entity list changed
• Update Synthesis pages if any were added in this run
• Update updated: date

Layer indexes (Sources/index.md, Wiki/index.md):

• Refresh cross-domain catalog for each layer

Root index (index.md):

• Refresh highlights: active projects, recent sessions, key entities
• Update counts

Step 7: Append to log.md

Append a single entry:

## [YYYY-MM-DD HH:MM] compile | <one-line summary>

- Pages touched: <list>
- Pages created: <list>
- Entities promoted: <list, or "none">
- Synthesis pages written: <list, or "none">
- Tags proposed: <list, or "none">
- Contradictions flagged: <list, or "none">
- Notes: <free-text observations, if any>

Step 8: Post-compile commit

git add -A
git commit -m "compile: <one-line summary>" -m "<body with same fields as log entry>"

Step 9: Session summary

Report back to the user with:

• One-line summary of what was done
• Counts: pages touched, created, promoted, synthesized
• Anything flagged for user review (proposed promotions, proposed tags, suspected contradictions)
• Anything that didn't get done and why (e.g., file with invalid frontmatter, file the agent wasn't sure how to categorize)
• Next step suggestion (lint pass, or nothing)

Stop conditions

Stop and report (do not proceed) if:

• Vault has uncommitted changes that are not from this run
• CLAUDE.md is missing or unreadable
• A page has malformed frontmatter that the agent cannot resolve confidently
• Git operations fail
• A proposed write would delete user content (always preserve; flag for review)

What this procedure does not do

• Restructure folders
• Delete pages
• Rename files
• Modify pages outside the vault
• Run lint (separate operation)
• Run a second compile pass after the first