reliquary/plugins/tome/skills/handoff/SKILL.md

name, description, disable-model-invocation, allowed-tools

name	description	disable-model-invocation	allowed-tools
handoff	After substantial implementation work, check whether the tome knowledge layer needs updating before you hand off — use impact analysis to find wiki docs and CLAUDE.md routers affected by the files you changed, triage what actually needs updating, and validate the result. Human-triggered. Use at the end of a feature, refactor, or structural change. Skip for bug fixes, minor refactors, and implementation details.	true	Bash(just:*), Bash(uv run:*), Bash(git:*)

Tome — Handoff

A targeted knowledge-layer check keyed to the files you just changed. Target: 5-10 minutes of agent time. This is NOT a full curation pass.

Step 1: Detect what changed

# Files changed on this branch vs main
git diff --name-only main...HEAD

# Or against a specific number of commits
git diff --name-only HEAD~3

If the change was a single targeted fix (one file, no structural impact), you can skip to Step 5 (validate). Impact analysis pays off for multi-file, structural, or architectural changes.

Step 2: Run impact analysis

Pipe the changed paths into the impact subcommand:

# Via just (preferred)
just tome impact src/path/file.rs src/path/other.rs

# Or pipe from git diff
git diff --name-only main...HEAD | uv run -q --script <tome-plugin-dir>/bin/knowledge.py impact

The output groups hits into four buckets:

Bucket	Meaning
Direct hits	Wiki docs whose source-paths list the exact changed file
Directory hits	Wiki docs whose source-paths list a parent directory
Control file hits	CLAUDE.md routers in ancestor directories
Potential stale	Same-module wiki docs (weak signal only)

Step 3: Triage — decide what actually needs updating

Work top-down by bucket priority: direct -> directory -> control -> potential.

Direct and directory hits — these wiki docs explicitly cover the changed code:

• Read the doc and check whether any stated facts are now wrong
• Look for: named components/systems that were renamed, removed, or replaced; described lifecycles that changed; documented hazards that were resolved or introduced; architectural claims that no longer hold

Control file hits — CLAUDE.md routers:

• Check if the module's stated purpose, key types, or entry points still match
• These usually only need updates for module renames, splits, or new cross-cutting dependencies

Potential stale — skim only if the change was structural:

• New module added, file moved, concept renamed -> worth a look
• Bug fix, refactor within same module -> skip

Most changes need no wiki updates. The triage step often concludes: nothing to do.

Step 4: Fix what is actually wrong

Update only what you can confirm is incorrect. Do not speculatively rewrite.

Update wiki docs when:

• A named component, system, plugin, or resource was renamed or removed
• A lifecycle or state machine changed (new states, different transitions)
• A new hazard or known failure mode was introduced
• A documented integration pattern no longer applies

Update CLAUDE.md routers when:

• The module's primary responsibility changed
• A new domain, plugin, or cross-cutting dependency was added
• Key entry-point files moved or were renamed

Do NOT update for:

• Bug fixes and implementation detail changes
• Internal refactors that don't change public contracts or architecture
• Performance tweaks, test additions, or formatting changes
• Content that is already accurate but could be "improved"

Adding new wiki content — only if the change introduced something the wiki should cover: a new domain, a new hazard class, a new architectural pattern. Apply the "earned place" test: would removing this force an agent to do thinking work, or just a tool call?

Step 5: Validate

just tome check

Confirms no broken links or structural issues were introduced. Fix any errors before handing off.