--- 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.0: Unconfigured workspace If no wiki root resolves because workspace routing is unconfigured, do not silently choose or initialize one. Skip the impossible schema/index reads and continue directly at Step F. After answering, follow the required capture flow. The capture skill is the sole owner of orphan preservation and the `project`, `main`, or `both` question. Do not add a second setup prompt here. Malformed or incomplete configured routing is an error, not this branch. ### Step A — Orient Read these files in order: 1. `/schema.md` — taxonomy, conventions, thresholds. 2. The relevant `//_index.md` for the question's apparent topic. If the question crosses categories or you cannot tell which category applies, read `/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). For each term, count how many entries it substring-matches (case-insensitive) in the title, the one-liner, or the tag list on that line. A term that hits 6 or more entries is a common term (the Explore band). Other hitting terms are rare terms. Do not keep a denylist of tag names; frequency on this index is the only test. Build the candidate set as follows: - If there is at least one rare term, start with pages that match at least one rare term. Otherwise start with pages that match at least one common term. - Then, for each common term, drop candidates that do not match it, unless that would leave zero pages; in that case skip that term. A page matches a term when that term substring-hits its title, one-liner, or tag list. 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: `` > > Wiki path: `` > > Run the orient procedure (read schema.md and the relevant _index.md), identify candidate pages with the same rare/common census as Step B (title, one-liner, tag list; 6 or more hits is common; rare terms select; common terms AND-filter unless that would leave zero pages), 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 or unconfigured workspace) Zero signal matches in `_index.md`, or Step A.0 found no configured wiki. 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 `//.md` followed by a brief relevance note OR a short quote (≤2 lines). - For each web source you drew from: cite as `[](<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.