g-eskayo/marvin/paper-dive

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