Ai Wiki Full

---
name: ai-wiki-full
description: File content into the knowledge base and place it under a topic hub with reciprocal links, creating the hub only if it passes the admission test. Use when the user asks to file a paper under a research direction, build or extend a topic map, or organise notes into a topic. For a single note without a hub, use ai-wiki instead.
---

# ai-wiki-full — file a note and place it under a topic

The full version of `/ai-wiki`: write the note as `/ai-wiki` does, then **place it under a research direction** with reciprocal links.

**First read `.claude/skills/ai-wiki/SKILL.md` and run its procedure (steps 1-7)**, then let this file replace step 6 and append step 8. The reference files are shared from `.claude/skills/ai-wiki/references/`; this skill does not duplicate them.

Which command to use:

| Situation | Use |
|---|---|
| Read a paper, save a conversation, file something quickly | `/ai-wiki` |
| Explicitly place a paper under a direction, build or extend a direction map, tidy a topic | `/ai-wiki-full` |

---

## Step 6 (replaced): place under a topic

### 6.1 Search before you build

`Glob` `Research/topics/` and **open and read S1 of every existing hub**. The default action is to **file under an existing topic**.

Only when no existing hub can hold it do you proceed to the admission test.

### 6.2 Admission test — all three must pass to create a new topic

Full criteria in `references/note-specs.md` under "What qualifies as a topic". In short:

1. **Can you name three other papers you would actually read that belong in it?** If not, it is not a topic — it is one paper.
2. **Could it hold 5-15 notes without becoming a jumble?** If not, it is too fine; it belongs as an S2 sub-area of an existing topic.
3. **Can no existing hub really hold it?** Answer only after reading their S1 sections.

**Any one failing means do not create it.** Link the paper note to the nearest existing hub and explain in S8's "files under topic" why it sits there. Where useful, add a sub-area row to that hub's S2 to accommodate it — **fine distinctions become sub-areas, not new files.**

> **A 1:1 ratio is a failure signal.** Count before acting: if the file count in `Research/topics/` approaches that of `Research/papers/`, the granularity is already wrong. The correct action then is to merge, not to add another.

### 6.3 All three pass: build the lightweight companion hub

`Read` `Templates/topic-plan.md`, fill it in place, and follow the **lightweight companion** column of the "Two modes" table in `references/note-specs.md`:

- S1 genuinely summarises what the broad direction is about (the recurring question, why it is hard, where the community disagrees), written for the user's future self.
- S2 gives 2-4 coarse sub-areas, each with a `research/<area>` or `method/<x>` tag. **Name sub-areas with a short self-explanatory phrase; never use A/B/C or 1/2/3 as the name** — these names get quoted into dozens of notes, into `active.md`, and into the generated map, and in those places the reader does not have S2 in front of them. Rationale and the incident behind it: wording test 3 in `references/note-specs.md`.
- S3 says "no systematic search run yet". **Never write speculative query strings.**
- S4 gives 3-5 recommended next reads **taken from this paper's own bibliography**, in clearly labelled provenance blocks (user-supplied / from bibliography / search hits — kept separate).
- S5 is one honest line, flagged as n=1 — but **when N papers arrive in one command, start at n=N**: the comparison table has N columns immediately, and patterns and contradictions are registered there and then. See "When several papers arrive together" below.

**Do not over-build it.** No `paper-search` run, no speculative sub-area taxonomy, no invented research plan, no query strings nobody ran. The user asked for a paper to be read; the hub is scaffolding, not the deliverable. ~10 minutes, ~40 lines.

### 6.4 Put the note in the topic's folder

Paper notes live in per-topic folders: `Research/papers/<topic-slug>/<paper-slug>.md`, where **the folder name is the hub's slug**.

- Filing under an existing topic → write into that existing folder.
- A new hub was created → create `Research/papers/<new-topic-slug>/` alongside it.
- The note was written at the `papers/` root by `/ai-wiki` and is only now being filed → move it into the subfolder **and change its embed prefix from `../../_attachments/` to `../../../_attachments/`**.

After moving a note, **rebuild the index** (`scripts/build-paper-index.py`) so the folder change is reflected in the topic column, and the next duplicate check searches current data.

> **This is the one step in this workflow that fails silently.** `[[wikilinks]]` resolve by filename anywhere in the vault, so moving a note never breaks a link; markdown image embeds are real relative paths, and a wrong depth shows up only as an image that does not render. Spot-check one image after moving. The attachment tree `_attachments/paper-figures/<paper-slug>/` **stays flat and does not follow the topic** — papers change topics, slugs do not.

### 6.5 Reciprocal linking (mandatory)

- The paper note links back to `[[<topic-slug>]]` (in "Related links", and named in S8's "files under topic").
- **The note's frontmatter must carry `subarea:` and `tagline:`** — the hub's S0.5 paper map is generated from them (below).
- The topic's **S4 queue row** gets its status and note link.
- Both directions, always — one missing side and the graph stops clustering.
- A paper that genuinely spans two topics: pick the dominant one for the reciprocal link and mention the other with a plain `[[wikilink]]`. **Never file the same paper under two hubs.**

> **S0.5's paper map is generated; never hand-write it.** Each note's `subarea:` (the sub-area **name**, copied verbatim from the hub's S2 first column; separate two with `、`, the first being the primary) and `tagline:` (one-line placement, **<=40 chars**) drive it. **The map's grouping order is read straight from S2's row order**, so a name that does not match S2 silently sorts last — no error. To change a placement, edit the frontmatter and re-run:
> ```bash
> python .claude/skills/ai-wiki/scripts/build-paper-index.py 0ai_wiki/Research/papers -o 0ai_wiki/Research/paper-index.md --maps
> ```
> `--maps` rewrites what sits between `<!-- PAPER-MAP:START … -->` and `<!-- PAPER-MAP:END -->` in each hub; hand-written sections are untouched. A new hub needs those two markers inserted first.
> **The old "S6 per-paper annotations" are abolished** — unscannable at 19 notes, useless at 30-40. S6 now holds **related hubs only**.

### 6.6 Cross-paper synthesis — mandatory when filing into an existing hub

S4 and S6 only hang the paper on the hub; **the hub's value is in S5**. New connections almost never come from looking for them in the abstract — they come from **checking the new paper item by item against the structures S5 already holds**: the comparison table, the numbered regularity, the logged contradictions. So this step has fixed moves, not a vague "remember to synthesise".

**Re-read S5's existing tables and numbered regularities first**, then land at least one of:

| Which one | What to write |
|---|---|
| **Consensus** (n≥2 with existing notes) | State n, and how the two pieces of evidence differ — different abstraction level / lab / task family. Two results from the same source are not n=2 |
| **Contradiction** | Lay out each side's evidence and name **the single cheapest experiment that would settle it** |
| **Nth instance of a logged regularity** | Say whether it is the same situation as the previous N−1, or a different one that is equally damaging |
| **New row in an existing comparison table** | Fill every column; if the paper occupies a position that did not exist on the table, say which axis the gap was on |
| **None of the above** | **Write "this paper produced no new cross-paper thread"** explicitly, then stop |

**That last row is a hard requirement.** Inventing something that looks like synthesis is worse than honestly recording none — it contaminates the basis for the next round's judgement.

**Which part of S5 it lands in** (structure and size discipline below):

| Content | Goes to |
|---|---|
| New row on a comparison table / new numbered regularity / new numbered contradiction | **S5.1 Structures** |
| A question that is still open | **S5.2**, under its sub-area, **<= 6 per sub-area** |
| An older question **this paper answered** | **Move it to S5.3**, recording what was asked / who answered / what the answer was / what gap remains. Do not leave it in place |

Also refresh the **note count and sub-area distribution** in the S0 abstract block and the status column in the sub-area table. Stale counts make the hub misinform the next round's decisions (this is the second place in the workflow that fails silently).

> **Reading order is a tool too.** An "ancestor" paper (the source that every later paper criticises) usually yields more when read **after** its critics than in chronological order — you can then check directly whether those critiques attack what it actually claimed or what everyone assumed it claimed. Likewise, two papers addressing the same problem setting that never cite each other yield more read side by side than either alone.

### 6.6b Size discipline — it has to stay scannable at 30-40 notes

A hub grows linearly with the paper count, and **a hub too long to scan is a hub that does nothing**. Hard rules:

| Where | Rule | Why |
|---|---|---|
| **S0.5 paper map** | Script-generated, one line per paper | The single entry point for "what is in this topic". Hand-written means drift |
| **S5.1 Structures** | Only **structure you can check item by item**: comparison tables, numbered regularities, numbered contradictions. No prose observations | A prose observation cannot be checked against a new paper three months later; a table can |
| **S5.2 Open questions** | **<= 6 per sub-area**; when full, move answered ones to S5.3 first | Otherwise it becomes a wish-list that only ever grows |
| **S4 reading queue** | Read rows become `~~struck~~ + read, see [[slug]]`; **do not keep the full rationale** | The rationale is already in the note |
| **`.claude/rules/active.md`** | **<= 1 line of <= 150 chars per paper, <= 6 KB total** | It is loaded in full every session. In one vault it reached **43 KB** (43% of it mirroring paper notes), burning ~11k tokens per turn |

**The test is not line count — it is whether you can answer "what is in this topic and where is it stuck" in 30 seconds.** If you cannot, restructure instead of appending.

### 6.7 Five notes is a recommendation threshold, not authorisation

When a lightweight hub reaches five linked notes, **say it is mature enough for a full plan, then stop**. Reaching the threshold authorises nothing: no expansion, no `paper-search`, until the user agrees.

S1-S4 are expanded only when the user **explicitly triggers** the topic search ("run the search for `<topic>`", "expand this direction", "complete this topic"). Absent that, S3 stays "no systematic search run yet" and S4 grows only from bibliographies.

**Expanding is not searching.** "Tidy up this topic" is not a search request: synthesise only from linked notes, user-supplied papers, and already-read bibliographies; open no search-hits block; state the evidence boundary out loud.

---

## When several papers arrive together

N papers at once is not "run the procedure N times". These four rules replace that naive reading.

### The admission test runs once — and N papers arriving together is itself evidence

The first question in 6.2 is whether you can name three further papers you would actually read that belong to the topic. When the user hands over three at once, **half of that question is already answered** — those three are in hand. So a batch clears admission more easily than a single paper, and that is correct rather than lax: the failure mode a hub guards against is a 1:1 topic-to-paper ratio, and a hub that starts at three papers is not that shape.

Questions 2 and 3 still have to be answered honestly: **can it hold 5–15 papers**, and **can an existing hub genuinely not hold it** (answer that after reading their S1 sections, not before).

### Choose the reading order yourself; do not follow the order the user typed

The note at the end of 6.6b that order is itself a tool is rarely load-bearing for one paper. **In a batch it is:**

- A **foundational paper that later work repeatedly criticises should be read after its critics** — that is the only way to check whether the criticisms address what it actually claimed or what it is remembered as claiming.
- Two papers in the **same problem setting that do not cite each other** should be read side by side.

Scan the years and the citation relations first (grep the later paper's bibliography for the earlier ones' first-author surnames), then fix the order and **state the order and the reason to the user** — it determines whether S5 can produce anything.

### The S5 synthesis happens once, after all N are read

**Do not append a paragraph to S5 after each paper.** That produces N paragraphs of "this one adds X" rather than a structure that can be checked line by line — precisely the prose accumulation 6.6b forbids.

Instead: once all N paper notes are written, re-read those N plus whatever S5 already holds, **in one pass**, and enter the rows per 6.6. For a new hub, S5 **starts at n=N, not n=1** — three papers arriving together means the comparison table has three columns from the start, and the patterns and contradictions are registered then.

### The closing scripts run once

`build-paper-index.py --maps` and `check-vault.py` only need one run **at the end**, not one per paper.

---

## Step 8 (appended): granularity maintenance

Each time this command runs, check once and **propose** (do not execute):

- **Merge candidates**: two hubs whose S1 sections substantially overlap, or a hub that has grown by one note in six months. Propose keeping the one with more papers as the primary hub, folding the other's content into its S2 and S6, and reducing the old file to a one-line redirect.
- **Upgrade candidates**: a lightweight hub that has reached five notes.
- **Split candidates**: a hub past roughly 15 notes where one S2 sub-area alone would hold five — only then is splitting justified, and the split-out topic passes the admission test by construction.

Merging, splitting, and upgrading **all require the user's agreement before execution**. Rebuild the index afterwards. When executing, **move the `Research/papers/<topic-slug>/` folder with the hub**: relocate notes from the absorbed folder into the surviving hub's folder and delete the empty directory. Folder-to-folder moves keep the same depth, so embed prefixes do not change.

---

## Self-check (in addition to the `/ai-wiki` checklist)

- [ ] Read S1 of every existing hub before considering a new one
- [ ] If a hub was created, all three admission tests were explicitly passed in the note or the conversation
- [ ] No hub was created merely to house one paper (the 1:1 check)
- [ ] Reciprocal links complete: paper note → topic, and the topic S4 queue row → paper note
- [ ] **S5 cross-paper synthesis done**: a consensus (with n and how the two sources differ) / a contradiction (with the cheapest settling experiment) / an Nth instance / a new comparison-table row — **or an explicit "this paper produced no new cross-paper thread"**. Nothing invented to look like synthesis
- [ ] **Landed in the right part**: structure into S5.1, still-open into S5.2 (that sub-area under 6), answered ones **moved** to S5.3 rather than left in place
- [ ] **The note's frontmatter carries `subarea:` (a name, never a letter) and `tagline:`**, and `--maps` was re-run to regenerate S0.5; no row landed at the end of the grouping (landing last = the name does not match S2)
- [ ] **No label anywhere is just an index** ("branch A", "shape B", "sub-area C") — sub-areas, taxonomies and threads all get self-explanatory names
- [ ] **S0's note count and sub-area distribution, and the S2 status column, match the actual file count**
- [ ] **`active.md` gained one line of <= 150 chars and the file is still <= 6 KB** (`wc -c .claude/rules/active.md`)
- [ ] **New prose written into the hub passes the same three wording tests** — S5 is where metaphor creeps back in first; **`.claude/rules/active.md` and `CLAUDE.md` are in scope too** (2026-09-06: an earlier sweep covered only the vault notes and the skills, and missed these two)
- [ ] The paper is filed under exactly one hub
- [ ] The note sits in `Research/papers/<topic-slug>/` and its embeds use `../../../_attachments/` (not `../../`), with one image spot-checked
- [ ] A new hub's S3 reads "no systematic search run yet" (unless the user explicitly asked for a search)
- [ ] S4's three provenance blocks are labelled and not merged into one table
- [ ] At the five-note threshold, only a recommendation was given — no unilateral upgrade

## Related

To write a single note without a hub, use `/ai-wiki`.
Full spec: `.claude/skills/ai-wiki/references/note-specs.md`. Tool choice: `.claude/skills/ai-wiki/references/tools.md`.