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

---
name: curate
description: >
  Run a bounded curation pass over the tome knowledge layer — using one of six
  curation methods (code-digest, reference-digest, explorer, concept-author,
  workpad-graduate, seal). Each method is independent and feeds specific wiki
  entry points. Human-triggered. Use periodically, or after a wave of changes
  has accumulated. Specify a method, or omit to get guidance on what's needed.
disable-model-invocation: true
allowed-tools: Bash(just:*), Bash(uv run:*), Read, Write, Glob, Grep, Agent
---

# Tome — Curate

## Orientation

The wiki grows through **curation methods** — independent strategies for producing
wiki content. Each method feeds specific entry points and can run alone.

Check the project's curation rules (in the project-specific tome overlay, e.g.
a `references/curation-rules.md` in the project's tome configuration) to see which
methods are active and what entry points they feed. If no curation rules exist, only
`code-digest` is available by default.

When invoked without a specific method, assess what's needed:
- Are inventories stale? -> run `code-digest`
- Are there reference docs without wiki digests? -> run `reference-digest`
- Is the wiki root a stub or generated placeholder? -> run `explorer`
- Are there wiki folders with no README? -> run `seal`

## Step 1: Refresh inventories (all methods)

```bash
just tome refresh
```

This regenerates `.inventory.md` files (gitignored) with the current state.

## Method: code-digest

*Baseline method. Reads source code, produces wiki docs.*

**Entry points**: `codebase/`, or project-equivalent source directories

1. Review `.inventory.md` for changes since last curation.
2. Curate NAV files: diff inventory against NAV, promote what earns its place.
3. Correct wiki claims that are now false. Flag conceptual drift.
4. Create new wiki docs only for genuinely new patterns, domains, or layers.
5. Apply the "earned place" test for all content.

### NAV files (inventory -> judgment)

NAV files are **selective, curated navigation** — not directory listings. The tool
produces `.inventory.md` with the exhaustive listing; your job is to decide what
earns a place in `NAV.md`.

1. Read `.inventory.md` (the full machine-generated inventory)
2. Read the existing `NAV.md`
3. **Diff**: What's new in the inventory that should be promoted to NAV? What's in
   NAV that no longer exists or isn't important enough?
4. Write to NAV only what earns its place — 5-15 key entry points with a sentence
   about *why each matters*, not just what it is.

When a NAV file has `status: stub`, it means it was seeded but never curated.
Curate it and change status to `authored`.

### Wiki documents

- Correct wiki claims you can confirm are now false.
- Flag possible conceptual drift; create new wiki documents for genuinely new
  patterns, domains, or layers (mark them `status: authored`).
- Do **not** broadly rewrite authored knowledge. Curation tracks *current
  understanding* — treat diffs as input signals, not find-and-replace targets.

## Method: reference-digest

*Reads authored reference docs, distills decisions into wiki.*

**Entry point**: `design/` (or project-equivalent)

1. Identify reference docs (e.g. `docs/topics/`, design specs, architecture guides).
2. For each doc without a wiki digest, or with a stale one:
   a. Read the reference doc.
   b. Extract decisions, invariants, lifecycle models, key constraints.
   c. Write a digest (50-100 lines) carrying the *thinking work* — not a summary
      of prose, but crystallized knowledge an agent needs.
   d. Use front matter with `source-paths` pointing to the reference doc.
3. Check existing digests for staleness: has the source doc changed since the
   digest was written?

**Front matter example:**
```yaml
---
status: authored
source-paths:
  - docs/topics/some-topic.md
---
```

**What a good digest contains:**
- The 3-7 key decisions the doc makes, each with 2-3 sentences of rationale
- Links to the full doc sections for details
- Cross-links to related wiki docs
- NOT a prose summary — the crystallized decisions and models

## Method: explorer

*An agent explores the project and writes what it learns.*

**Entry point**: Wiki root (`README.md` or `index.md`)

This is the most open-ended method. The agent acts like a person spending a day
with the codebase and writing down what they learn.

1. Explore broadly: scan directories, read READMEs, check build config, run the
   build if possible.
2. Write a wiki frontpage explaining:
   - What the project is and why it exists
   - How it works at a high level
   - Where the interesting, complex, or surprising parts are
   - What's well-documented vs. what's still unclear
3. Create stub pages for areas that need deeper investigation.
   Use `status: stub` front matter.
4. Mark confidence levels in prose: "I'm confident about X" vs "I think Y works
   like Z but haven't verified."

**What makes this different from code-digest:**
- Top-down (understand project -> describe) vs bottom-up (read file -> write doc)
- Stubs and uncertainty markers are features, not gaps
- Reads like something a person wrote, not a generated inventory
- The explorer's judgment about what's interesting IS the value

**Output tone:** Conversational but precise. "The network model is surprisingly
complex — the server doesn't replicate transforms at all, instead..." Not:
"This section covers the network model implementation details."

## Method: concept-author

*Direct authoring of non-code knowledge.*

**Entry point**: `concepts/`, or project-appropriate branch

For knowledge that has no source code counterpart: domain rules, taxonomy,
design principles, or other conceptual knowledge unique to the project.

1. Identify concepts that exist in the team's heads or in scattered brainstorms
   but have no structured home.
2. Author wiki docs directly. The wiki *is* the source of truth.
3. Use `source-paths: []` in front matter (no backing file).

**Brainstorm boundary:** Brainstorms are exploration, not source material. If a
brainstorm produced a lasting decision, that decision is authored here as
standalone knowledge — not as a digest of the brainstorm. A one-line origin note
is acceptable:
`> Design rationale explored in /docs/brainstorm/topic.md`

## Method: workpad-graduate

*Promotes lasting research into the wiki.*

**Entry point**: Wherever the knowledge fits

Workpad content is ephemeral by design. But sometimes research produces lasting
knowledge that should live in the wiki.

1. User (or curator) identifies a workpad note with lasting value.
2. Distill the knowledge — not the research process — into a wiki doc.
3. The wiki doc stands alone. It does NOT reference the workpad.
4. The workpad note stays where it is (historical record).

**Key rule:** The wiki never cites or links to workpad content. The graduation
step distills and relocates. If someone deletes the workpad note, the wiki doc
must still make complete sense.

**Reverse flow:** When starting new research, read the wiki first to understand
what's already known. The wiki is both a sink for lasting knowledge and a source
for new exploration.

## Method: seal

*Ensures every wiki folder has a README that orients a reader.*

**Entry point**: All wiki folders

The finishing pass that makes the wiki feel complete rather than scaffolded.

1. Walk every wiki folder.
2. For each folder, check:
   - Does it have a README.md (or equivalent orientation doc)?
   - Does the README explain what this section covers?
   - Does it mention what's well-documented vs. still thin?
3. For folders missing a README: write one. It should orient a reader who landed
   here without context — what's in this section, why it matters, what to read
   first.
4. For folders with only a NAV.md: the NAV is navigation, not orientation. Add a
   README that introduces the section. NAV remains for structured links.
5. Review glossary completeness: scan wiki docs for terms that should be in the
   glossary but aren't.

**What sealing fixes:**
- Folders with only a NAV.md and no orientation
- Entry points that read like directory listings instead of introductions
- Missing context about what a section covers and what's still thin
- A root README that only talks about codebase as an entry point

## Cross-Method Rules

These apply regardless of which method is active.

### File structure (non-codebase wiki)

Outside `wiki/codebase/`, wiki documents follow the **flat-file-first** rule:

- **Default**: Create `topic.md` as a flat file in its parent directory.
- **Promote**: Only create `topic/README.md` when you're also creating child pages
  under that topic. Move the content from `topic.md` into `topic/README.md`.
- **Split threshold**: If a wiki page grows past ~150 lines or covers 3+ distinct
  sub-concepts that could stand alone, consider splitting into a folder with children.

Inside `wiki/codebase/`, the mirror structure uses `directory/README.md` to match
the source tree layout.

### Triage

If content doesn't belong where you found it:

- Add it to `wiki/_triage.md` with a `found-in` note
- Don't place it in the wrong wiki doc just to avoid the triage inbox
- Categories determine exit path:
  - `cross-cutting-pattern` / `design-decision` -> wiki docs
  - `convention` -> project skill or CLAUDE.md
  - `todo` / `future-idea` -> workpad or issue tracker (exits wiki entirely)

### Warnings must be machine-visible

`tome context` surfaces hazards only from `## Warnings` H2 sections in control files
(CLAUDE.md / AGENTS.md). A hazard written as free prose in a router is invisible to
the navigation plane. When curating a control file that carries active hazards, put
them as bullets under a `## Warnings` section — one line each, stating what breaks
and what to do instead.

### The "earned place" test

Before adding content to the wiki, ask: *Would removing this force an agent to do
thinking work to reconstruct it, or just a tool call?*

- If a tool call (`ls`, `grep`, `git log`) can recover it -> it doesn't belong
- If understanding the codebase, patterns, or design rationale is required -> it earns its place

### Glossary consistency

During any curation method, check `/wiki/glossary.md`:

- If a wiki doc introduces a term that's in the glossary, use the glossary's name
- If you encounter a term that should be in the glossary but isn't, add it
- If a glossary definition has drifted from reality, update it
- Mark uncertain additions as `[unverified]`
- Every curation method that introduces new terminology must feed the glossary

### `@AGENTS.md` include pattern

When writing or updating CLAUDE.md routers, use `@AGENTS.md` includes for routing
tables that exceed ~15 lines. This keeps CLAUDE.md small and readable while
carrying the machine-readable routing in a framework-agnostic include:

```markdown
# Module Name
@AGENTS.md
```

Works in Claude Code (which resolves `@`-includes) and other agent frameworks.

## Step 3: Validate

```bash
just tome check
```

Verify no broken links or structural issues were introduced.