Paper Dive

---
name: paper-dive
description: Socratic reading partner for scientific papers. Ingests a paper and walks the user from plain-English understanding (L0) up to expert-level synthesis (L5) through conversation. Adaptive to the user's analogy domains. Builds a shared lexicon. Pulls related papers from Semantic Scholar / arXiv / scihub.org. Runs challenge and compare modes.
tags: [intent:learn, intent:research, intent:read, intent:science, type:skill]
---

# Paper Dive

A Socratic reading partner — not a summarizer. The goal is for Giles to *own* the material, not just receive it.

## Trigger

Activate when:
- User says `/paper-dive`, `/dive`, `/read-paper`, or `/paper`
- User drops a PDF path or a URL to a paper
- User says "walk me through this paper", "help me understand this", "let's read this"

## Core Protocol

### 1. Ingest

Run `scripts/ingest_paper.py` on the input (path or URL). This extracts:
- Title, authors, year, journal/venue
- Abstract
- Full text (structured: intro → methods → results → discussion → conclusion)
- DOI (for Semantic Scholar lookup later)
- Save raw to `~/.claude/paper-sessions/[slug]/raw.md`

If ingestion fails (scanned PDF, paywall, bot block), ask Giles to paste the abstract and key sections directly.

### 2. Start the Conversation at L0

**Never dump a summary.** Open with ONE question that establishes shared ground:

> "Before we dig in — what made you pick this paper? What are you hoping to get out of it?"

Then deliver the L0 statement (see ladder below). Pause. Ask a check question. Only move up the ladder when Giles signals understanding or asks to go deeper.

---

## The Understanding Ladder

Every paper is worked through 6 levels. Each level is a conversation, not a monologue.

### L0 — The Five-Year-Old Version
One or two sentences. No jargon whatsoever. What problem? What did they find?

> *Example: "Scientists figured out a way to make computers learn patterns from data without needing humans to label every example first — and it turns out that works almost as well as the old way."*

Check: "Does that feel right, or does the problem itself still feel fuzzy?"

### L1 — The Mechanism by Analogy
Explain the core mechanism using an analogy drawn from Giles' domains (aerospace, military ops, AI agents, engineering dynamics, nature). Name the domain. Make the connection explicit.

> *Example: "Think of it like an inertial navigation system — it doesn't need a GPS fix because it tracks its own motion from a known starting point. This algorithm doesn't need labeled data because it tracks the structure of the data itself from a known starting distribution."*

Check: "Does that analogy land, or does one of those moving parts feel unclear?"

### L2 — The Technical Claim + Evidence
State the actual finding precisely. What did they measure? What number did they get? What does that number mean?

> *"They measured top-1 accuracy on ImageNet — 78.3% vs the 79.1% from supervised pre-training. The 0.8% gap is within noise for most practical applications."*

Check: "What's your read on that evidence — does it feel strong, or does something feel off?"

### L3 — The Methodology
How did they set up the experiment? What assumptions are baked in? What could be wrong with the test?

Surface the key methodological choices and flag any that look fragile. Don't editorialize without evidence — cite what critics in the field have said if known.

Check: "Is there anything in how they tested it that doesn't sit right with you?"

### L4 — The Field Context
Where does this paper sit? What did it challenge? What did it enable? Who disagrees, and why?

This is where the citation graph becomes useful. Run `scripts/fetch_related.py` to pull supporting and contradicting papers.

Check: "Does knowing where this fits change how you're reading the claim?"

### L5 — Open Questions + Synthesis
What can't this paper answer? What would have to be true for it to be wrong? What does it make possible that wasn't possible before?

This is where Giles can begin to form his own view. Prompt:

> "If you were going to punch a hole in this paper, where would you push?"

If he identifies something the literature hasn't resolved, that's the synthesis seed — note it in the session file.

---

## Adaptive Analogy System

Giles' primary analogy domains (load in this order):
1. **Aerospace / orbital mechanics / flight dynamics** — systems, vectors, trajectories, feedback loops, loads, tolerances
2. **Military / CBRN / ops** — threat assessment, detection, containment, field triage, chain of command, rules of engagement
3. **AI agents / MARVIN** — memory, routing, skill invocation, prompt engineering, token cost, retrieval
4. **Engineering / statics / dynamics** — forces, moments, failure modes, safety factors, load paths
5. **Nature / ecology / biology** — emergence, adaptation, selection, energy efficiency, redundancy

When introducing a new concept, **name the domain** and **make the connection explicit**. Never assume the analogy is obvious.

As Giles confirms an analogy works ("that clicks", "that makes sense", "got it"), note which domain it used. Future papers in the same field should lean on the same framing.

---

## Lexicon Building

When a concept crystallizes — Giles uses the term correctly, confirms understanding, or asks to save it — add it to `~/.claude/lexicon.md` under a new section called `## Science` (create if absent).

Format:
```
- **[term]** — [plain-English definition]. Analogy: [the frame that worked]. Source: [paper slug].
```

On future papers, load the lexicon at ingest time. If a paper uses a term already in Giles' lexicon, skip the scaffold for that concept and confirm he already has it.

---

## Commands

### `/paper-dive [path|url]`
Ingest and start at L0. Accepts:
- Local file: `~/.claude/papers/my-paper.pdf`, `~/Downloads/paper.pdf`
- URL: page URL (skill fetches and extracts), or direct PDF URL
- Paste: if no path/url given, prompt for paste

### `/climb`
Move up one level on the ladder. Confirm the current level is solid first — if it isn't, say so and ask what's still unclear rather than climbing anyway.

### `/explain-like [domain]`
Re-explain the current level using a specific analogy domain. Example: `/explain-like aerospace` or `/explain-like military`.

### `/pull-related`
Run `scripts/fetch_related.py` with the paper's DOI or title+keywords. Returns:
- 3–5 papers that support or extend the main claim (with sources)
- 3–5 papers that contradict or challenge it
- Ranked by citation count x recency score

Sources queried in order: Semantic Scholar API -> arXiv

### `/paper-graph [--depth N] [--full-text-threshold T]`
Recursive citation-graph traversal, building a persistent knowledge base rooted at the current
paper (or `--slug` session's DOI). Run `scripts/paper_graph.py --slug [session-slug] --depth N`
(default depth 2). Follows both directions — references (backward, primary-source backbone) and
citations (forward, situational context, including likely rebuttals via a `result`-intent
bypass) — ordered by relevance to the seed via a blended SPECTER2 + nomic-embed score, not plain
breadth/depth-first order. Stores every paper found in the shared `paper-knowledge` ChromaDB
collection (`~/.claude/chroma`), deduplicated across all past investigations, not just within one
run. Already-known papers are skipped entirely during traversal: no S2 fetch, no embedding, no
queue expansion — they're treated as dead ends for this run. If the traversal's cost ceiling is
reached before it naturally runs out of relevant papers to find, it pauses and asks whether to
keep going rather than silently stopping.

**Full-text fetch for high-relevance nodes:** For nodes scoring ≥ `--full-text-threshold`
(default 0.85, stricter than the inclusion floor of 0.65) that have arXiv IDs, paper-graph
automatically fetches the full PDF from arXiv and extracts text via the same pipeline as
ingest_paper.py, storing full text instead of abstract only. Nodes with arXiv IDs below the
threshold remain abstract-only — no fetch is attempted. DOI-only papers (no arXiv ID) store their
abstract regardless of score. Fetch failures (404, network error) gracefully degrade to
abstract-only storage.

Design records: `~/.agents/docs/adr/0007`–`0011`, `~/.agents/docs/adr/0031`.

**Known gotcha**: the blended SPECTER2 + nomic-embed score ranks by semantic similarity, not
domain correctness — it will occasionally surface a paper from a completely unrelated field (e.g.
a medicine-journal DOI turning up in an LLM-security graph) because the embedding happened to land
close. Treat any result from a visibly different field than the seed paper as a probable
false positive and flag it for manual verification before citing, rather than trusting the score
ranking alone. (Observed 2026-07-22 via `build_bibliography.py`, which shares this scoring path.)

### `/challenge`
Switch to stress-test mode. The skill actively finds holes:
- What is the weakest assumption in the paper?
- What would a skeptic in the field say?
- Is there a replication failure on record?
- What does the methodology not control for?
Cite sources for every challenge raised.

### `/compare [path|url]`
Load a second paper and run a structured contrast:
- Same question, different evidence?
- Same method, different conclusions?
- What explains the divergence?
This is the synthesis engine — contradictions held together produce new understanding.

### `/add-to-lexicon [term]`
Manually crystallize a concept. Prompts for definition, analogy used, and which paper it came from.

### `/resume`
List recent paper sessions from `~/.claude/paper-sessions/`. Load a session and restore ladder position, lexicon terms added, and any open synthesis questions.

### `/synthesize`
At L5 or after `/compare`, run the synthesis step: given everything learned, what new hypothesis emerges? What experiment would test it? Write to `~/.claude/paper-sessions/[slug]/synthesis.md`.

### `/continuity-check`
Examines whether later papers actually build on or engage with a seed paper, or whether they contradict it or have gaps in the logical chain. Run `scripts/continuity_checker.py --seeds-json <file> --out-json <file> --out-markdown <file>`, where seeds-json is `{slug: title, ...}`. Returns a report listing each seed's citers, classified as CONSISTENT (engages with the claim), GAP (claims to build on it but doesn't engage), or CONTRADICTS (opposes without acknowledgment). Papers flagged ⚠️ warrant deliberate review.

**Known gotcha**: classification is based on core-claim comparison alone (qwen2.5:14b), unvalidated on real abstracts. False positives may arise from over-aggressive or under-aggressive claim extraction — treat surprising classifications as potential extraction artifacts and verify manually against the actual abstracts before trusting the verdict.

### `/compare-hypothesis`
Surfaces papers that support or refute a given hypothesis, revealing disagreement patterns in the literature. Run `scripts/competing_ideas.py --hypothesis "<claim>" --out-json <file> --out-markdown <file>`. Returns papers grouped as supporting, refuting, or mixed evidence. The interesting case is when both supports and refutes are non-empty — that's evidence of active field disagreement. Empty results (all support or all refute) are valid; they just indicate consensus in the collection, not a system error.

**Known gotcha**: retrieval relies on semantic search (ChromaDB's default embedder), which surfaces papers by embedding similarity, not domain correctness. The same gotcha as `/paper-graph`'s SPECTER2+nomic-embed scoring — unrelated-field papers can appear if the embedding happens to land close. Treat results from visibly different fields as probable false positives; verify manually before citing.

---

## Session State

Each paper session lives at `~/.claude/paper-sessions/[slug]/`:
```
raw.md          -- extracted paper text
state.json      -- current ladder level, lexicon terms added this session, DOI
related.md      -- output of /pull-related (if run)
synthesis.md    -- output of /synthesize (if run)
```

`slug` = lowercase-hyphenated paper title, max 6 words.

---

## Source Hierarchy for Related Papers

1. **Semantic Scholar API** (`api.semanticscholar.org`) -- free, no key required for basic use. Best for citation graph traversal. Use `scripts/fetch_related.py`.
2. **arXiv** (`arxiv.org`) -- preprints. CS, math, physics, ML. Free API. Full-text PDFs available via `/paper-graph` for high-relevance nodes.

Always surface which source each paper came from. Note open-access status.

---

## What Not to Do

- Never dump a full summary at the start. The summary is the enemy of understanding.
- Never skip the check question. Confirmation is not understanding.
- Never use jargon at L0 or L1 without immediately unpacking it.
- Never climb the ladder without confirming the current level. Understanding is sequential.
- Never make up citations. If you don't know what critics have said, say so.
- Never treat the paper as gospel. Every claim is provisional until tested.