wiki-update

---
name: wiki-update
description: Use when revising existing wiki pages because knowledge has changed, a new piece of information updates or contradicts existing content, or the user wants to directly edit wiki content with LLM assistance.
license: MIT
---

# Wiki Update

Revise existing wiki pages. Always show diffs before writing. Always log. Always cite the source of new information.

## Pre-condition

Find `SCHEMA.md` (search from cwd upward, or `~/wikis/`). If not found, tell the user to run `wiki-init` first. Read it to get wiki root path and conventions.

**Link style.** Read `link_style:` from `SCHEMA.md`. If the field is missing or `<wiki-root>/config/link-style.md` does not exist, default to `obsidian` (`[[slug]]`). Otherwise, read `<wiki-root>/config/link-style.md` for the emit and parse rules. Use the `## Parse` rule when scanning existing pages for cross-references; use the `## Emit` rule whenever you write new cross-references or citations.

## Process

### 1. Identify what to update

The user may provide:
- **Specific page names** — update those pages
- **New information** — regenerate the index (`python bin/generate-index.py`), read `wiki/index.md` to find affected pages, then read those pages
- **A lint report** — work through its recommendations item by item

### 2. For each page to update

Read the current content in full. Propose the change:

> **Current:** `<quote the existing text>`
> **Proposed:** `<replacement text>`
> **Reason:** `<why this change is warranted>`
> **Source:** `<URL, file path, or description of where this information comes from>`

**Always include Source.** An edit without a source citation creates untraceability — future you won't know why the change was made.

**If a proposed edit introduces a new `[[slug]]`,** the target must resolve to an
existing `wiki/pages/<slug>.md` (or a page being created in this operation) before you
write it — see the Concept Identity rule in `SCHEMA.md`. Never edit in a link to a slug
you have not confirmed.

Ask for confirmation before writing each page. Do not batch-apply changes without per-page confirmation.

### 3. Check for downstream effects

After identifying the primary pages to update, scan all of `wiki/pages/` for cross-references to those pages using the `## Parse` rule from `config/link-style.md`. For each page that links to an updated page:

- Does the update change anything that page asserts?
- If yes: flag it explicitly — "<other-page slug> may also need updating based on this change"
- Offer to update it with the same confirm-before-write flow

### 4. Contradiction sweep

If the new information contradicts something in the wiki: search all pages for the contradicted claim before updating. It may appear in more than one place. Update all occurrences, not just the most obvious one.

### 5. Regenerate `wiki/index.md`

Never hand-edit the index. If the page's one-line summary or category changed, edit the
`summary` / `category` **frontmatter** on the page itself. Always bump the page's
`updated` date (leave `created` untouched). Then regenerate:

```
python bin/generate-index.py
```

### 6. Update `wiki/overview.md`

Re-read `overview.md`. If the updates shift the overall synthesis (new understanding, resolved open question, changed key claim), propose edits to overview.md using the same confirm-before-write flow.

### 7. Record the operation

Per SCHEMA's **Operation Log & Commit Convention**:
- **Git wiki:** stage the changes and suggest a commit (default Conventional Commits
  `docs:` for an update, plus the trailer); commit on the user's confirmation.
  ```
  docs: <what changed, briefly>

  Wiki-Op: update
  ```
- **Non-git wiki:** append to `wiki/log.md` (do not skip if it exists):
  ```
  ## [<today>] update | <list of updated page slugs>
  Reason: <brief description of what changed and why>
  Source: <URL or description>
  ```

## Common Mistakes

- **Updating without citing the source** — Always include where the new information came from. This makes the wiki auditable.
- **Skipping the downstream check** — An update that contradicts a page's content while leaving pages that link to it unchanged creates silent inconsistency.
- **Skipping the log** — Every change must be recorded: a git wiki commits it (with the `Wiki-Op:` trailer); a non-git wiki appends to `log.md`.
- **Batch-writing without confirmation** — Show each diff individually. The user may accept some changes and reject others.
- **Appending instead of updating** — Do not add `## [date] update` sections to page bodies. Edit the relevant section in-place, bump the `updated` frontmatter date, and log the change in `log.md`. If you find existing date-stamped sections, offer to integrate them in-place as part of the update.
- **Inventing `[[slug]]` links in an edit** — A revision must not introduce a cross-reference to a slug that resolves to nothing. Confirm the target exists (or create it); see the Concept Identity rule in `SCHEMA.md`.