wiki-update

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 — " 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.