--- name: karpathy-wiki-read description: | Read protocol for the main agent. Load on demand when answering ANY user question (per Iron Rule 4 in `using-karpathy-wiki/SKILL.md`). Defines the deterministic 6-step orientation ladder for finding wiki coverage of a question, when to inline-read vs spawn an Explore subagent vs fall through to web search, and the cite contract every wiki-grounded answer must satisfy. ---

# karpathy-wiki read

You loaded this skill because the user asked a question (per Iron Rule 4 in the loader: NO ANSWERING ANY USER QUESTION WITHOUT ORIENTING FIRST). Your job is to determine whether the wiki covers the answer, retrieve the coverage, and either cite-and-answer from the wiki or fall through to web search — without ever pre-classifying the question as "wiki-irrelevant."

## The 6-step ladder

Every step is deterministic. There is no agent judgement at branch points; each branch is gated on a counted or boolean condition.

### Step A — Orient

Read these files in order:

1. `<wiki>/schema.md` — taxonomy, conventions, thresholds. 2. The relevant `<wiki>/<category>/_index.md` for the question's apparent topic. If the question crosses categories or you cannot tell which category applies, read `<wiki>/index.md` (the root MOC).

If you have already oriented earlier in this session, skip to Step B — the schema and index content are already in your working memory. Orientation is once per session.

### Step B — Count signal-matching candidates

Extract the question's signal terms: meaningful nouns, proper-noun phrases, technical terms, version numbers, tool names. Skip stopwords ("the", "what", "how", "do", "is").

Walk the relevant `_index.md` (already in memory from Step A). A page is a candidate if ANY signal term:

- Substring-matches its title (case-insensitive), OR - Matches a tag (exact, case-insensitive), OR - Appears in its one-line summary.

Count the candidates. Branch on count:

- **0 candidates** → Step F (cold-result path) - **1-5 candidates** → Step C (inline read) - **6+ candidates** → Step E (Explore subagent)

The threshold is 5/6, not your judgement. Do not "feel" your way to a different branch.

### Step C — Inline read

Read all candidate pages in full. After reading, ask exactly:

> Does the union of these pages contain every claim my answer would make?

Branch on the answer:

- **YES** → cite + answer (see "Cite contract" below). Done. - **NO** → Step D (gap-fill via web search).

### Step D — Gap-fill via web search

The wiki covered part of the answer; the rest needs fresh information. For each claim your answer would make that the wiki did NOT cover:

1. Web search for the specific claim (use `WebFetch` or `WebSearch`). 2. Cite the web source(s) for the gap-filled claim.

Compose the answer using BOTH the wiki citations (for what it covered) and the web citations (for what it didn't).

After answering, **always** write a capture noting the gap. The wiki should grow toward questions it failed to answer fully. The capture's title is the question; the body documents what the wiki had and what was missing. Use `karpathy-wiki-capture/SKILL.md` for the capture authoring procedure.

### Step E — Explore subagent

Spawn an Explore subagent with this prompt shape:

> Question: `<the user's question, verbatim>` > > Wiki path: `<wiki absolute path>` > > Run the orient procedure (read schema.md and the relevant _index.md), identify candidate pages by signal-term match, read all candidates in full (no cap on page count — your context is isolated), and return a synthesis. > > The synthesis must: > - Cite every page it draws from (path + one-line relevance note per page). > - Cover the question completely (no truncation for brevity if the answer is genuinely long). > - Be as terse as possible while preserving every wiki-specific claim, decision, and contradiction. Terseness is a property of the writing, not a target word count. > - If the wiki does not cover the question, say so explicitly and return an empty page-list. Do NOT attempt to fall through to web search yourself; the main agent handles that.

When the subagent returns:

- **If it returned a synthesis with cited pages** → use the synthesis as the answer's basis. Add conversational framing as needed. Cite the pages the subagent cited. - **If it reported "wiki does not cover"** → Step D (web search + capture the gap).

The subagent dispatch maps to the patterns in your `~/.claude/CLAUDE.md` Task Delegation rule: this is a context-isolation case where the main agent needs the synthesis, not the page contents.

### Step F — Cold result (no candidates)

Zero signal matches in `_index.md`. The wiki has no coverage for this question.

1. Web search for the answer (`WebFetch` or `WebSearch`). 2. Cite the web source(s) in the answer. 3. **Always** write a capture so the next session is not cold for this topic. The capture's title is the question; the body documents what was found and where (the URLs you searched). Use `karpathy-wiki-capture/SKILL.md`.

A cold result is not a failure — it is the wiki telling you it has a gap, and you closing the gap.

## Cite contract

Every wiki-grounded answer must include citations the user can verify. Format:

- For each wiki page you drew from: cite as `<wiki>/<category>/<page>.md` followed by a brief relevance note OR a short quote (≤2 lines). - For each web source you drew from: cite as `[<title>](<url>)`. - Citations appear inline near the claim they support, not in a footer block, so the user can check each claim against its source.

If your answer makes a claim with no citation, that claim came from training data — flag it explicitly: *"(from training data; not in wiki)."* This is the **only** case where uncited claims are allowed, and they must be flagged.

## What goes in this skill — and what doesn't

This skill covers the read-from-wiki protocol only. It does NOT cover:

- Capture authoring (when a question reveals a wiki gap, the capture flow lives in `karpathy-wiki-capture/SKILL.md`). - Page-format conventions, manifest protocol, validator contract — those live in `karpathy-wiki-ingest/SKILL.md` and apply only to the spawned ingester. - Iron laws and the orient-first rule itself — those live in the loader (`using-karpathy-wiki/SKILL.md`).

If you find yourself needing capture or ingest mechanics while running this protocol, load the appropriate sibling skill — do not improvise.