--- name: ar9av/wiki-update source: https://app.decimal.ai/s/ar9av-wiki-update@1/SKILL.md source_sha256: 6229adf02e23 --- # Wiki Update — Sync Any Project to Your Wiki You are distilling knowledge from the current project into the user's Obsidian wiki. This skill works from any project directory, not just the obsidian-wiki repo. ## Before You Start 1. **Resolve config** — follow the Config Resolution Protocol in `llm-wiki/SKILL.md` (inline `@name` override → walk up CWD for `.env` → `~/.obsidian-wiki/config` → prompt setup). This gives `OBSIDIAN_VAULT_PATH`, `OBSIDIAN_WIKI_REPO`, `OBSIDIAN_LINK_FORMAT` (`wikilink` default or `markdown`), and optional QMD settings such as `QMD_WIKI_COLLECTION`. Works from any project directory. 3. Read `$OBSIDIAN_VAULT_PATH/.manifest.json` to check if this project has been synced before. 4. Read `$OBSIDIAN_VAULT_PATH/index.md` to know what the wiki already contains. When writing internal links in Steps 4–5, apply the link format from `llm-wiki/SKILL.md` (Link Format section) using the `OBSIDIAN_LINK_FORMAT` value. ## Step 1: Understand the Project Figure out what this project is by scanning the current working directory: - `README.md`, docs/, any markdown files - Source structure (frameworks, languages, key abstractions) - `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml` or whatever defines the project - Git log (focus on commit messages that signal decisions, not "fix typo" stuff) - Claude memory files if they exist (`.claude/` in the project) Derive a clean project name from the directory name. ## Step 2: Compute the Delta Check `.manifest.json` for this project: - **First time?** Full scan. Everything is new. - **Synced before?** Look at `last_commit_synced`. Before computing the delta, verify the stored SHA is still reachable: ```bash git merge-base --is-ancestor HEAD ``` - **Exit 0 (ancestor):** Safe. Run `git log ..HEAD --oneline` to see what changed. - **Exit 1 (not an ancestor — rebase or force-push occurred):** The stored SHA is no longer in this branch's history. Warn the user: *"Stored commit `` is no longer reachable — branch may have been rebased or force-pushed. Falling back to full scan."* Then treat as first-time sync: re-scan everything and update `last_commit_synced` to the current HEAD SHA at the end of Step 6. If nothing meaningful changed since last sync, tell the user and stop. ## Step 3: Decide What to Distill This is the core question from Karpathy's pattern: **what would you want to know about this project if you came back in 3 months with zero context?** Worth distilling: - Architecture decisions and *why* they were made - Patterns discovered while building (things you'd Google again otherwise) - What tools, services, APIs the project depends on and how they're wired together - Key abstractions, how they connect, what the mental model is - Trade-offs that were evaluated, what was picked and why - Things learned while building that aren't obvious from reading the code Not worth distilling: - File listings, boilerplate, config that's obvious - Individual bug fixes with no broader lesson - Dependency versions, lock file contents - Implementation details the code already says clearly - Routine changes anyone could read from the diff The heuristic: **if reading the codebase answers the question, don't wiki it. If you'd have to re-derive the reasoning by reading git blame across 20 commits, wiki it.** ## Step 4: Distill into Wiki Pages ### Project-specific knowledge Goes under `$VAULT/projects//`: ``` projects// ├── .md ← project overview (named after the project, NOT _project.md) ├── concepts/ ← project-specific ideas, architectures ├── skills/ ← project-specific how-tos, patterns └── references/ ← project-specific source summaries ``` The overview page (`.md`) should have: - What the project is (one paragraph) - Key concepts and how they connect - Links to project-specific and global wiki pages ### Global knowledge Things that aren't project-specific go in the global categories: | What you found | Where it goes | |---|---| | A general concept learned | `concepts/` | | A reusable pattern or technique | `skills/` | | A tool/service/person | `entities/` | | Cross-project analysis | `synthesis/` | ### Page format Every page needs YAML frontmatter: ```markdown --- title: >- Page Title category: concepts tags: [tag1, tag2] sources: [projects/] summary: >- One or two sentences (≤200 chars) describing what this page covers. provenance: extracted: 0.6 inferred: 0.35 ambiguous: 0.05 base_confidence: 0.59 lifecycle: draft lifecycle_changed: TIMESTAMP_DATE created: TIMESTAMP updated: TIMESTAMP --- Use folded scalar syntax (summary: >-) for title and summary to keep frontmatter parser-safe across punctuation (:, #, quotes) without escaping rules. Keep the title and summary contents indented by two spaces under summary: >-. # Page Title - A fact the codebase or a doc actually states. - A reason the design works this way. ^[inferred] Use [[wikilinks]] to connect to other pages. ``` **Write a `summary:` frontmatter field** on every new/updated page (1–2 sentences, ≤200 chars), using `>-` folded style. For project sync, a good summary answers "what does this page tell me about the project I wouldn't guess from its title?" This field powers cheap retrieval by `wiki-query`. **Apply provenance markers** per `llm-wiki` (Provenance Markers section). For project sync specifically: - **Extracted** — anything visible in the code, config, or a doc/commit message: file structure, dependencies, function signatures, what a file does. - **Inferred** — *why* a decision was made, design rationale, trade-offs, "the team chose X because Y" — unless a commit message, doc, or ADR states it explicitly. - **Ambiguous** — when the code and docs disagree, or when there's clearly an in-progress migration with two patterns living side by side. Compute the rough fractions and write the `provenance:` block on every new/updated page. ### Updating vs creating - If a page already exists in the vault, **merge** new information into it. Don't create duplicates. - If you're adding to an existing page, update the `updated` timestamp and add the new source. - Check `index.md` to see what's already there before creating anything new. ## Step 5: Cross-link After creating/updating pages: - Add `[[wikilinks]]` from new pages to existing related pages - Add `[[wikilinks]]` from existing pages back to the new ones where relevant - Link the project overview to all project-specific pages and relevant global pages ## Step 6: Update Tracking ### Update `.manifest.json` Add or update this project's entry: ```json { "projects": { "": { "source_cwd": "/absolute/path/to/project", "last_synced": "TIMESTAMP", "last_commit_synced": "abc123f", "pages_in_vault": ["projects//.md", "..."] } } } ``` ### Update `index.md` Add entries for any new pages created. ### Update `log.md` Append: ``` - [TIMESTAMP] WIKI_UPDATE project= pages_updated=X pages_created=Y source_cwd=/path/to/project ``` ### Update `hot.md` Read `$OBSIDIAN_VAULT_PATH/hot.md` (create from the template in `wiki-ingest` if missing). Rewrite **Recent Activity** with what was just synced — last 3 operations max. Update **Active Threads** if this project is an ongoing focus. Update **Key Takeaways** with the most important architectural insight or decision surfaced during this sync. Update `updated` timestamp. Write conceptually: "Synced obsidian-wiki — added wiki-capture and wiki-research skills, core new capabilities are autonomous web research and conversation capture." ## Step 7: Refresh QMD Wiki Index (optional — requires `QMD_WIKI_COLLECTION`) **GUARD: If `$QMD_WIKI_COLLECTION` is empty or unset, skip this step.** The markdown vault is the source of truth; QMD is only a search index. Run this step only after pages, `.manifest.json`, `index.md`, `log.md`, and `hot.md` have been written. If Step 2 found no meaningful changes and the sync stopped early, do not refresh QMD. This refresh currently requires the local QMD CLI. Use `$QMD_CLI` if set; otherwise use `qmd`. If the CLI is unavailable or returns an error, do not roll back the wiki update; report that the wiki was updated but QMD refresh was skipped or failed. For CLI refresh: ```bash ${QMD_CLI:-qmd} update ``` If the output says new hashes need vectors, or if pages were created/updated and embeddings may be stale, run: ```bash ${QMD_CLI:-qmd} embed ``` Verify at least one created or materially updated page is visible in the wiki collection: ```bash ${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/projects//.md" -l 5 ``` If the exact `qmd://` path is uncertain, use: ```bash ${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION" | rg "" ``` Record QMD refresh in the final report as one of: - `QMD refreshed: update + embed + verified` - `QMD skipped: QMD_WIKI_COLLECTION unset` - `QMD skipped: qmd CLI unavailable` - `QMD failed: ` ## Tips - **Be aggressive about merging.** If the project uses React Server Components, don't create a new page if `concepts/react-server-components.md` already exists. Update the existing one and add this project as a source. - **Consult the tag taxonomy.** Read `$VAULT/_meta/taxonomy.md` if it exists, and use canonical tags. - **Don't copy code.** Distill the *knowledge*, not the implementation. "This project uses a debounced search pattern with 300ms delay" is useful. Pasting the actual debounce function is not. - **Project overview is the anchor.** The `.md` file is what you'd read to get oriented. Make it good.