---
name: handoff
description: >
  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.
disable-model-invocation: true
allowed-tools: 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

```bash
# 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:

```bash
# 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

```bash
just tome check
```

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