Lambenthan/empiricalwiki / i18n/en/skills/ingest
ingest
VerifiedIngest a paper into the wiki — creates pages (papers + concepts + people + claims) and builds all cross-references and graph edges. Trigger whenever the user says "ingest", "add this paper", drops a `.pdf` / `.tex` / arXiv URL, or asks to fold a paper into the knowledge base.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.6 KB |
| references/cross-references.md | markdown | 7.0 KB |
| references/dedup-policy.md | markdown | 5.2 KB |
| references/error-handling.md | markdown | 3.9 KB |
| references/init-mode.md | markdown | 5.1 KB |
| references/pdf-preprocessing.md | markdown | 3.9 KB |
references/cross-references.md
View on GitHub# /ingest Cross-References
Open this reference when you are writing a link on any wiki page. Every forward link has a reverse obligation (except to foundations). The table below is the contract.
## Forward → reverse obligation
Mirrors the matrix in the root `CLAUDE.md` ("Cross-Reference Rules"), trimmed to the edges `/ingest` actually writes:
| Forward action (what you write on page A) | Required reverse action (what you also write on page B in the same turn) |
|-------------------------------------------|--------------------------------------------------------------------------|
| `papers/P` writes `Related: [[concept-K]]` | `concepts/K` appends `P` to `key_papers` |
| `papers/P` writes `[[person-R]]` (in Key authors) | `people/R` appends `P` to `Key papers` |
| `papers/P` writes `supports: [[claim-C]]` | `claims/C` appends `{source: P, type: supports}` to `evidence` |
| `papers/P` writes `supports: [[claim-C]]` but paper contradicts claim | use `type: contradicts` in the evidence entry |
| `claims/C` writes `source_papers: [[paper-P]]` | `papers/P` appends `C` to `## Related` |
| `concepts/K` writes `key_papers: [[paper-P]]` | `papers/P` appends `K` to `## Related` |
| any page writes `[[foundation-X]]` | **no reverse link** — foundations are terminal |
Writing a forward link without its reverse is the most common way `/check` surfaces `missing-field` errors. Doing both together eliminates the class entirely.
## Foundations are terminal
Never modify a foundation page from `/ingest`. No `key_papers` field, no back-reference of any kind. A paper linking to a foundation leaves a trace only in two places:
- the paper page's `## Related` contains `[[foundation-slug]]`
- `wiki/graph/edges.jsonl` contains the `paper → foundation` edge with type `derived_from`
Foundations are created only by `/prefill`. `/ingest` never creates foundations, even when a concept candidate looks foundational and has no match. In that case, route the candidate through the ordinary concept path (possibly creating a new concept page), and let the user seed a foundation later if they want to.
## Paper-to-concept semantic edges
Papers relate to concepts by using, introducing, extending, or critiquing
them. Every paper-to-concept semantic edge must include `--confidence high|medium|low`.
Edge-type selection:
- **`introduces_concept`** — strict novelty only: the paper explicitly proposes, coins, defines, or names the concept as a contribution.
- **`uses_concept`** — default for an existing concept that the paper relies on without materially changing it.
- **`extends_concept`** — the paper modifies, generalizes, specializes, or formalizes an existing concept.
- **`critiques_concept`** — the paper argues that a concept has limitations, failure modes, or invalid assumptions.
When uncertain between `introduces_concept` and `uses_concept`, choose
`uses_concept`. When uncertain between `uses_concept` and `extends_concept`,
choose `uses_concept`. Do not emit `paper → concept` edges of type `supports` or
plain `extends`.
The tool rejects missing confidence/evidence and legacy paper-to-concept edge
types on new writes.
## Paper-to-paper edges
The bibliographic layer is separate from the semantic layer:
- always write `graph/citations.jsonl` with `type: cites` when a reference resolves to an existing `wiki/papers/{slug}.md`
- write `graph/edges.jsonl` only when the paper text gives a clear semantic cue
- do not force every citation into a semantic edge
Paper-to-paper semantic edges are intentionally sparse. They require a concrete
relationship between the papers' contributions, not just shared topic,
modality, architecture family, benchmark family, or high-level method words. If
the same statement would be true for dozens of papers in the wiki, skip the
paper-to-paper edge and rely on topic/concept links plus citations instead.
Semantic edge-type selection:
- **`same_problem_as`** — symmetric; both papers attack the same concrete task, research question, or problem formulation, so their proposed answers are directly comparable. Do not use this for broad areas like "attention", "video generation", or "LLM evaluation".
- **`similar_method_to`** — symmetric; both papers share a distinctive mechanism, formulation, training strategy, or algorithmic design. Do not use this for generic families like "uses transformers", "uses diffusion", or "uses RL".
- **`complementary_to`** — symmetric; the approaches or components can be combined in a technically specific way, and the paper text or method details give evidence for that compatibility. Do not use this merely because both could belong to the same future system.
- **`builds_on`** — directional; this paper directly depends on, adapts, or extends the other paper's specific method, formulation, dataset, result, or system. Do not use this for vague inspiration.
- **`compares_against`** — directional; this paper uses the other paper as an explicit baseline, comparator, or ablation reference.
- **`improves_on`** — directional; this paper explicitly claims better quality, efficiency, robustness, simplicity, or scope than the other paper in a comparable setting.
- **`challenges`** — directional; this paper disputes, weakens, or presents counter-evidence against the other paper's result, assumption, or framing.
- **`surveys`** — directional; this paper is a survey, benchmark, taxonomy, or position work that summarizes the other paper or its line of work.
All paper-to-paper semantic edges must include `--confidence high|medium|low`.
For symmetric types, `tools/research_wiki.py add-edge` canonicalizes the
endpoint order and writes `symmetric: true`.
The tool rejects missing confidence/evidence and legacy paper-paper edge types
on new writes.
- **none / skip** — if none of the above cleanly fits, skip the edge. Graph noise is worse than a missing edge.
When in doubt, skip. Paper-paper semantic edges are for high-signal local
relationships, not clustering by field.
## Writing both sides atomically
For every link `/ingest` writes, the reverse should land in the same turn. In practice that means:
1. Decide on the link.
2. Write the forward entry on the originating page.
3. Write the reverse entry on the target page.
4. If the link also corresponds to a semantic graph edge (paper↔concept, paper↔claim, paper↔paper, paper→foundation), emit it via `tools/research_wiki.py add-edge`.
5. If a paper reference resolves to an existing paper page, emit the bibliographic row via `tools/research_wiki.py add-citation`.
This pattern keeps `/check` from flagging half-written links in its next run. It also makes rollbacks straightforward: if a paper ingest is aborted, you can undo both sides together by reverting the paper's edits.
## What `/ingest` does not check here
`/ingest` writes forward and reverse links as it goes, but it does not verify that every pre-existing link in the wiki still has its reverse. That is a full-graph audit and belongs to `/check`. Do not read the entire `wiki/` to look for broken back-references during ingest — the time and token cost is large and the work is redundant with `/check`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |