Wiki Handoff

Wiki Handoff

Overview

Bidirectional ritual for the project wiki:

• Persist what was learned, decided, built, or deferred so a future session can pick up cold.
• Bridge mid-session checkpoints to /compact so the active window stays healthy without losing facts.

The wiki schema is project-specific. Always discover and read the schema file first — it overrides every default in this skill.

Modes

Choose based on what the user said and on whether the session is ending or continuing.

Don't Use When

• Trivial sessions (one-line bugfix, formatting). The git log is enough.
• Information is already obvious from git log / git blame / the code itself. The wiki is for non-derivable knowledge.

Pre-flight (always, both modes)

Run before any writes:

1. Locate the schema. See Schema Discovery. If none found → Initialize Wiki.
2. Detect git. git rev-parse --is-inside-work-tree 2>/dev/null. If false, set git=off — the workflow still writes files but skips commit / push / status steps. Tell the user once at the end.
3. Read existing pages you plan to touch. Extend, never overwrite. If new info contradicts old, flag it inline.
4. Use the absolute YYYY-MM-DD from the system context. Never write "today" or "yesterday".

Schema Discovery

Search this order; first hit wins:

1. wiki/CLAUDE.md
2. wiki/SCHEMA.md
3. ./CLAUDE.md — only if it contains the LLM Wiki pattern (mentions index.md, log.md, raw/wiki/schema layers, or "LLM Wiki")
4. ./WIKI.md

If the schema specifies a directory layout, frontmatter shape, link convention, or topic scope, defer to it over the defaults in this skill. In particular:

• Link style — schema picks [[wikilinks]] vs [text](path.md). Don't override.
• Subdirectories — if existing wiki/ is flat, write flat. Don't mkdir entities/concepts/sources/comparisons/ unless schema says so.
• Page types — use the schema's taxonomy; the default table below is fallback only.

Initialize Wiki (first-time setup)

Trigger: schema discovery returned nothing and wiki/ is either absent or contains no markdown files.

If wiki/ has files but no schema, do not bootstrap a parallel layout. Instead, infer the existing shape (flat vs categorized, link style, frontmatter) and write a schema file that matches before proceeding.

Steps:

1. Locate the bundled seed. It lives at seeds/llm-wiki.md next to this SKILL.md. If you don't know the SKILL.md path, try in order: ~/.agents/skills/wiki-handoff/seeds/llm-wiki.md, ~/Developments/wiki-handoff/seeds/llm-wiki.md. Last resort: find ~ -path '*wiki-handoff/seeds/llm-wiki.md' 2>/dev/null | head -1. Do not fetch from the internet — the seed is bundled to be offline-safe.
2. Copy it to wiki/CLAUDE.md.
3. Ask the user one question before scaffolding directories:

   Flat layout (wiki/<topic>.md) or categorized (wiki/{entities,concepts,sources,comparisons}/)? Default: flat.

4. Create empty wiki/index.md with # Index heading and one section per category (matching the chosen layout).
5. Create empty wiki/log.md with # Log heading.
6. Create empty raw/sources/ for source pointers.
7. If git is on, commit as a separate scope: wiki: initialize from llm-wiki seed.
8. Tell the user the wiki was initialized from the seed and point them at wiki/CLAUDE.md to adjust the schema before the next handoff. Then proceed with the requested mode.

What to Capture — the Non-derivable Gate

Before writing each page or paragraph, answer this:

Could a future session derive this from git log, the code, CLAUDE.md, or an existing wiki page?

• Yes → skip. Write nothing.
• No → write it.

This gate is the wiki's only defense against bloat. Apply it strictly.

Workflow — handoff

1. Pre-flight.
2. Inventory the session. From the conversation, list:
   • New things introduced → entity pages
   • Concepts/techniques that recur → concept pages (non-trivial only)
   • External sources cited → source pages (only if a raw/ doc exists)
   • Existing pages that need an update Apply the non-derivable gate to every item before writing.
3. Write the pages. Follow the schema's frontmatter and link style. Be terse — a 5-line page is fine.
4. Update the index. One line per new page in the right category.
5. Append to the log. Format: ## [YYYY-MM-DD] <op> | <short title> followed by 1–3 lines.
6. Git on → commit per scope (wiki: <subject>), push, verify git status clean. Git off → tell the user the files are written but not versioned; suggest git init if they want handoff durability across machines.

Workflow — snapshot

The point of snapshot is to make /compact safe: persist the load-bearing facts to wiki before compacting, so the compactor doesn't need to recall them.

1. Pre-flight.
2. Diff the session. What's new since this conversation started that isn't already in the wiki? Apply the non-derivable gate.
3. Write only the deltas. Skip the full index overhaul that handoff does — just write the new/extended pages and append one log line: ## [YYYY-MM-DD] snapshot | <subject>.
4. Produce the recommended /compact string and show it verbatim:

   /compact focus on <current task>. The following are now persisted in the wiki — drop from active window:
   - <wiki/page-1.md> — <what it covers>
   - <wiki/page-2.md> — <what it covers>
   Keep in window: <current diff / test failures / in-progress artifact>.
   

5. Don't push in snapshot mode unless the user asks. Optional commit is fine; default is no commit, just files on disk.

Frontmatter (default — verify against schema)

---
title: <page title>
type: entity | concept | source | comparison | overview | note
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [list of raw/ filenames cited, or []]
tags: [optional]
---

Page Type Quick Reference (default — verify against schema)

If the project uses a flat wiki/<topic>.md layout, ignore the path column and write flat.

Pre-push Sanity (git only)

Before git push, in this order:

1. git status — only the files you intended.
2. git log --oneline -5 — commit messages match project style.
3. git diff origin/<branch>..HEAD — review what's about to land.

If a commit message reads "what I did" instead of "what changed and why", reword before pushing.

Common Mistakes

• Skipping schema discovery. Always run it first; defer to whatever it returns over this skill's defaults.
• Bootstrapping a parallel layout. If wiki/ already has files but no schema file, do not mkdir new subdirs — read the existing layout and write a schema file that matches it.
• Overwriting existing pages. Read them first; extend.
• Padding with code or file structure. That's already in the code and git log. The wiki captures why and what surprised us.
• Forgetting the log.md entry. Without it, the operation is invisible to a grep "^## \[" audit.
• Forgetting the index. New pages must be discoverable from the catalog, not just by file scan.
• Relative dates. "Today" / "yesterday" / "Thursday" rot. Always write the absolute YYYY-MM-DD.
• Committing but not pushing in handoff. A handoff that lives only on your machine is not a handoff.
• Pushing in snapshot without asking. Snapshot is mid-session; the user may not want a remote commit yet.
• Single mega-commit. Match the project's split style — one commit per scope (e.g. one for code, one for wiki:).
• Skipping the non-derivable gate. The wiki bloats fast if every session writes a play-by-play. Be ruthless.

Red Flags — Stop and Fix

• About to write without locating the schema → run Schema Discovery first.
• About to bootstrap when wiki/ already has content → infer the existing layout instead and write a matching schema.
• About to write ## [today] or ## [yesterday] → use the absolute YYYY-MM-DD.
• Page has no inbound links from index.md → orphan; add the index entry.
• Commit message is update wiki → too vague; name the page or topic.
• git push fails for auth → don't --force; ask the user.
• In snapshot mode but the recommended /compact string is missing → that bridge is the whole point of snapshot; produce it.
• Bootstrap step about to fetch from a URL → wrong; the seed is bundled at seeds/llm-wiki.md.