literature-survey-skill
A Claude Code skill that takes PhD students from a pile of papers to a synthesized understanding of what the field knows, what it doesn't, and where to push next. Intent → Triage → Deepen → Synthesize.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/snl-ucsb--literature-survey-skill)HTML
<a href="/listings/snl-ucsb--literature-survey-skill"><img src="/api/listings/snl-ucsb--literature-survey-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/SNL-UCSB/literature-survey-skill.git cd literature-survey-skill ./setup.sh
This installs the skill to `~/.claude/skills/survey/`. Four commands become available:
/survey intent — Capture your goals, expertise, and survey archetype /survey triage — Map the landscape, prioritize reading depth /survey deepen — Structured deep reading with craft and visualization extraction /survey synthesize — Cross-paper analysis for your deliverable /survey expand — Propose and evaluate corpus growth
Start with `/survey intent`. The skill guides you from there.
Prerequisites
The [NotebookLM MCP CLI](https://github.com/jacob-bd/notebooklm-mcp-cli) must be configured as an MCP server in your Claude Code setup. **[Follow the setup guide](NOTEBOOKLM_SETUP.md)** — it covers installation, Google authentication, and MCP registration in ~5 minutes.
Manual Install
Copy `SKILL.md` to `~/.claude/skills/survey/SKILL.md`. Copy `reference/` and `templates/` alongside it.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 473 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: survey
- description: "Literature survey assistant with four modes: /survey intent (capture student goals, expertise, and success criteria), /survey triage (landscape mapping via NotebookLM), /survey deepen (structured reading with craft and visualization extraction), /survey synthesize (cross-paper analysis for related work, area exams, gap identification). Also: /survey expand (corpus growth proposals). Use when students mention reading papers, literature review, related work, area exam prep, paper corpus, or any systematic reading task."
- ---
- # Literature Survey Skill — Intent → Triage → Deepen → Synthesize
- This skill helps PhD students build a deep, synthesized corpus of research insights through a structured, cognitively-aware workflow. It combines Kahneman's dual-process theory, Keshav's three-pass reading method, first-principles analysis, and NotebookLM as a backend query engine.
- **Architecture:** All student work lives locally (Obsidian/filesystem). NotebookLM is a query backend only — papers go in, grounded answers come out.
- **Modes:**
- - `/survey intent` — Capture what you're trying to learn and where you're starting from
- - `/survey triage` — Map the landscape, prioritize reading depth
- - `/survey deepen` — Structured reading with craft and visualization extraction
- - `/survey synthesize` — Cross-paper analysis for deliverables
- - `/survey expand` — Structured corpus growth proposals
- If the student invokes `/survey` without a mode, ask which mode they want. If they seem unsure or are starting a new survey, begin with intent.
- **Prerequisites:** NotebookLM MCP CLI must be configured. See `reference/notebooklm_tools.md` for setup.
- ---
- ## Mode 1: Intent — "What are you trying to learn?"
- **Purpose:** Capture the student's survey goals, expertise level, and success criteria BEFORE any paper is read. This shapes all subsequent modes.
- **Do NOT create any NotebookLM notebooks in this mode. Do NOT ingest any papers. The goal is purely clarifying intent.**
- ### Step 1: Identify the survey archetype
- Ask the student which best describes their situation:
- > Before we look at any papers, I need to understand what kind of survey this is. Which best describes you?
- >
- > **A. Explorer** — "I'm entering a new area and need to understand the landscape."
- > **B. Investigator** — "I have specific questions I need answered from the literature."
- > **C. Validator** — "I think I've found a gap/idea and want to confirm it's novel."
- > **D. Examiner** — "I need to demonstrate comprehensive mastery for an exam or survey paper."
- Each archetype has different defaults:
- | Archetype | Triage scope | Deepen targets | Pass 3 count | Synthesize output |
- |-----------|-------------|----------------|-------------|-------------------|
- | Explorer | 50-100+ papers | 8-15 at Pass 2 | 2-3 | Landscape overview |
- | Investigator | 10-25 papers | 5-10 at Pass 2 | 3-5 | Technique comparison |
- | Validator | 15-30 papers | 3-5 closest at Pass 2+3 | 3-5 | Positioning argument |
- | Examiner | 80-150+ papers | 15-25 at Pass 2 | 5-8 | Full narrative survey |
- ### Step 2: Assess expertise level
- Ask calibration questions for the chosen topic:
- > 1. **Vocabulary check:** Can you name 3 key technical terms in this area and define each in one sentence?
- > 2. **Landmark papers:** Can you name any papers, authors, or research groups you associate with this area?
- > 3. **Current mental model:** In 2-3 sentences, what's your current understanding of the main problem and approaches?
- > 4. **Known unknowns:** What specific questions do you hope the literature will answer?
- **Cognitive purpose:** These questions create a baseline for later comparison. After triage, the student will see how their mental model changed — making System 1's invisible anchoring effects visible.
- ### Step 3: Define success criteria
- > 1. **Deliverable:** Related work section? Area exam presentation? Gap analysis? Idea validation?
- > 2. **Scope:** Approximately how many papers do you expect to cover?
- > 3. **Timeline:** When do you need the output?
- > 4. **Time budget:** How many hours per week can you invest?
- ### Step 4: Check for advisor input
- > Has your advisor or collaborator recommended specific papers or threads to explore? Any "must-read" papers with suggested reading depth?
- ### Step 5: Generate the intent profile
- Write a `survey_intent.md` file using the template from `templates/survey_intent_template.md`. Save it to the student's survey directory:
- ```
- literature-survey/surveys/<topic-slug>/survey_intent.md
- ```
- Also create the directory structure:
- ```
- surveys/<topic-slug>/
- ├── survey_intent.md
- ├── pdfs/
- ├── papers/
- │ └── figures/
- ├── synthesis/
- ├── corpus_log.md
- ├── backlog.md
- └── nlm_config.md
- ```
- Tell the student: "Your survey intent is captured. Run `/survey triage` when you're ready to start mapping the landscape."
- ---
- ## Mode 2: Triage — "What's in this pile?"
- **Purpose:** Rapid Pass 1 over a corpus of papers using NotebookLM. Map the landscape and decide where to invest deeper reading. The archetype from intent mode shapes scope and clustering.
- ### Step 1: Set up NotebookLM backend
- Read the student's `survey_intent.md` and `nlm_config.md`. If no notebook exists yet:
- ```
- notebook_create(title="survey-<topic-slug>")
- chat_configure(notebook_id=<id>, goal="custom",
- custom_prompt="You are a research corpus query engine for a PhD student
- surveying [topic]. The student is an [archetype] with goals: [from intent].
- Always cite specific papers and quote relevant passages.",
- response_length="longer")
- tag(action="add", notebook_id=<id>, tags=["survey", "<topic>", "<term>"])
- ```
- Save the notebook_id to `nlm_config.md`.
- ### Step 2: Seed the corpus
- Ask the student for their initial papers (PDFs, URLs, BibTeX). For each paper:
- 1. **Acquire the PDF locally** using the priority chain:
- - Student already has the file → copy to `pdfs/YYYY_author_shorttitle.pdf`
- - Open-access URL (Arxiv, university repo) → download via `wget`
- - Semantic Scholar API → query for open-access PDF URL
- - Prompt the student for upload or URL
- 2. **Ingest into NotebookLM** (async for large batches):
- ```
- source_add(notebook_id=<id>, source_type="file", file=<path>, wait=False)
- ```
- 3. **Log in `corpus_log.md`** with status "ingesting".
- While papers load (3-5 min for 15+ papers), use the time productively — refine intent, discuss the topic, let the student start reading local PDFs if they want.
- ### Step 3: Generate Pass 1 summaries
- Once sources are ready, for each paper query NLM:
- ```
- notebook_query(notebook_id=<id>,
- query="For [title] by [author]: provide CATEGORY (measurement/systems-building/theory/survey),
- PROBLEM (one sentence), CONTRIBUTION (exact quote of main claim), EVALUATION (system/dataset/testbed),
- KEY REFERENCES (3-5 most cited references), RELEVANCE to survey goals (high/medium/low)")
- ```
- Write each response to a local file: `papers/YYYY_author_shorttitle.md` with a `[Pass 1]` header.
- ### Step 4: Generate landscape map
- Query NLM for a cross-corpus landscape:
- ```
- notebook_query(notebook_id=<id>,
- query="Group all papers by PROBLEM addressed (3-5 major threads). For each thread, list papers
- and methodology. Identify chronological patterns. WYSIATI CHECK: What problem areas or
- methodologies are absent? What would a skeptical reviewer say is missing?")
- ```
- Write to `survey_triage.md`.
- ### Step 5: WYSIATI check and intent comparison
- **This is a System 2 checkpoint.** Show the student their initial mental model (from `survey_intent.md`) alongside the landscape map:
- > "Here's what you thought the area looked like when you started. Here's what the corpus actually shows. What's different? What surprised you?"
- ### Step 6: Prioritize reading depth
- Help the student categorize each paper against their time budget:
- - **Pass 1 only** — background knowledge
- - **Pass 2 recommended** — relevant to core thread
- - **Pass 3 required** — foundational, must deeply understand
- Update `survey_triage.md` with the prioritized reading list.
- ### Step 7: Surface expansion candidates
- ```
- notebook_query(notebook_id=<id>,
- query="Which references appear in 3+ papers but are NOT sources in this notebook?
- For each, explain why it might be important to add.")
- ```
- Append candidates to `corpus_log.md` with reason=FOUNDATIONAL. Present to student for Add/Bookmark/Skip decision (see `/survey expand` protocol).
- ---
- ## Mode 3: Deepen — "What does this paper really say?"
- **Purpose:** Structured Pass 2 and Pass 3 reading for individual papers. Forces System 2 engagement, captures insights locally, uses NLM for grounded extraction and calibration.
- ### Step 1: Select a paper
- Ask which paper from the triage reading list. Read their existing paper note if one exists.
- ### Step 2: Pass 2 protocol
- Run four NLM queries and write results to the local paper note:
- **a. Claim extraction:**
- ```
- notebook_query: "For [title]: Quote the 3 most important claims with section/page references."
- ```
- **b. Evidence audit:**
- ```
- notebook_query: "For [title]: For each claim, what evidence is provided? Rate as strong/moderate/weak."
- ```
- **c. Methodology probe:**
- ```
- notebook_query: "For [title]: Describe evaluation setup. What explicit and implicit assumptions?
- What would break if workload/scale/topology changed?"
- ```
- **d. Dependency extraction:**
- ```
- notebook_query: "For [title]: What results from other papers does this depend on?
- Which dependencies might not hold in other contexts?"
- ```
- Write all responses to the paper's local note as a `[Pass 2]` section.
- ### Step 3: Calibration check (System 2 prosthetic)
- After the student has read the paper themselves, compare their understanding with NLM's grounded extraction:
- 1. Ask the student: "In one sentence, what is this paper's main contribution?"
- 2. Query NLM: "Quote the exact main contribution claim from the abstract or introduction."
- 3. Show both side by side in a `[Calibration]` section. Highlight the specificity gap.
- ### Step 4: First-principles decomposition
- ```
- notebook_query: "For [title], analyze along four dimensions:
- STATE: What state does the system manage?
- TIME: What timescales matter?
- COORDINATION: How do components coordinate?
- INTERFACE: What are the boundaries between components?
- Quote specific passages as evidence."
- ```
- Write to the paper note as `[First-Principles]` section.
- ### Step 5: Pass 3 — Virtual re-implementation (foundational papers only)
- Ask the student:
- - "If you had to build this system from scratch with the same goals, what would your design look like?"
- - "What assumptions are never explicitly stated?"
- - "Write three critical questions a skeptical PC member would ask."
- ### Step 6: Writing craft extraction (Pass 3+ papers the student admires)
- Read `reference/writing_craft_moves.md` for the full framework. Query NLM and guide the student through:
- **a. Introduction anatomy — the six-move formula:**
- ```
- notebook_query: "For [title], analyze the INTRODUCTION:
- MOVE 1 (Stakes): How does it open? Specific actors/applications/dollar amounts?
- MOVE 2 (Problem Gap): Structural or quantitative? Numbered limitations?
- MOVE 3 (Key Abstraction): Does it coin a memorable, citable term?
- MOVE 4 (Design Intuition): One-paragraph mental model? Overview figure?
- MOVE 5 (Contributions): Claims with evidence, or process descriptions? Numbered?
- MOVE 6 (Results Preview): Concrete headline numbers?
- Quote specific passages."
- ```
- **b. Evaluation architecture:**
- ```
- notebook_query: "For [title], analyze the EVALUATION:
- CLAIM-EVIDENCE MAP: List every intro claim → evaluation subsection → figure/table.
- SETUP: Compressed or technical report?
- DEEP DIVE: Results disaggregated by meaningful dimensions?
- TAKEAWAYS: Explicit takeaway after every experiment cluster?
- ABLATION: Shows each component contributes?"
- ```
- **c. Design section craft:**
- ```
- notebook_query: "For [title], analyze the DESIGN:
- Opens with abstraction or implementation?
- 'Why' move — justification via negative result?
- Named components? Key configurable 'knob'?"
- ```
- **d. Related work positioning:**
- Ask the student: How many categories? Structural or quantitative limitations? Explicit positioning sentence?
- **e. Peak observation:** What is the single most memorable insight — the thing you'd cite 10 years from now?
- **f. Lessons for my writing:** The student captures what they want to adopt for their own papers.
- Write to paper note as `[Craft]` section. Also append key lessons to `synthesis/writing_craft_corpus.md`.
- ### Step 7: Visualization extraction (all Pass 2+ papers)
- Read `reference/viz_analysis_guide.md`. Query NLM and guide the student through:
- **a. Figure inventory:**
- ```
- notebook_query: "For [title]: List every figure and table. For each: caption, role
- (overview/comparison/deep-dive/ablation/case-study), claim it supports, encoding used.
- Which is the headline figure?"
- ```
- **b. Visual argument analysis (2-3 key figures):**
- ```
- notebook_query: "For [title], for the 2-3 most important figures:
- What claim does each support? Describe encoding choices (axes, scale, color, faceting).
- WHY those choices — does the encoding serve the argument?
- What does the figure NOT show that would be useful?"
- ```
- **c. Figure extraction from local PDF:** If the student wants key figures extracted, use PyMuPDF on the local PDF in `pdfs/`, or prompt for manual screenshots. Save to `papers/figures/`.
- Write to paper note as `[Visualization]` section. Append best-practice examples to `synthesis/viz_patterns.md`.
- ### Output
- The local paper note (`papers/YYYY_author_shorttitle.md`) grows through the mode:
- `[Pass 1]` → `[Pass 2]` → `[Calibration]` → `[First-Principles]` → `[Craft]` → `[Visualization]` → `[My Notes]`
- ---
- ## Mode 4: Synthesize — "What connects all of this?"
- **Purpose:** Cross-paper synthesis for a specific deliverable. Uses NLM cross-corpus queries, writes all results locally.
- ### Step 1: Select synthesis goal
- The student chooses (informed by their intent profile):
- - **Related work section** — organized thematic narrative
- - **Area exam presentation** — breadth + depth + frontier identification
- - **Research gap identification** — systematic analysis of what's missing
- - **New idea synthesis** — creative recombination of insights
- ### Step 2: Invariant matrix
- ```
- notebook_query: "For every paper, build a comparison matrix:
- State management | Primary timescale | Coordination model | Interface design.
- Highlight where papers make fundamentally different choices."
- ```
- Write to `synthesis/invariant_matrix.md`. Student annotates locally.
- ### Step 3: Dependency graph
- ```
- notebook_query: "Identify cases where one paper's design DEPENDS ON an assumption
- another paper challenges. Quote the assumption and the challenging evidence."
- ```
- Write to `synthesis/dependency_graph.md`.
- ### Step 4: Gap identification
- ```
- notebook_query: "If [bandwidth/latency/scale] changed by 10x, which solutions still work?
- Which break? What new problems emerge that no paper addresses?"
- ```
- Also ask: "Looking at the invariant matrix — are there combinations no paper explores? Missing methodologies?"
- Write to `synthesis/gap_analysis.md`.
- ### Step 5: Cross-survey synthesis (if multiple survey notebooks exist)
- ```
- cross_notebook_query(query="How do approaches to [dimension] differ between
- [survey A] and [survey B]?", tags=["survey"])
- ```
- ### Step 6: Narrative construction
- Based on the synthesis goal, generate the deliverable draft:
- - **Related work:** Thematic threads with intellectual arcs, not chronological lists. Each thread: "These papers address X by solving Y, but none handle Z — our contribution."
- - **Area exam:** Breadth across subfield + depth on 2-3 foundational papers + frontier identification + student's own position.
- - **Gap analysis:** Constraint-change analysis → candidate problems with first-principles justification.
- - **New ideas:** "Paper A solves X under constraint C1. C1 is changing because of [trend]. Under C2, Paper A breaks because [dependency]. New approach needs [design principle]."
- ### Step 7: WYSIATI final audit
- Before finalizing:
- > "What perspectives are missing? What would someone from [adjacent field] say? Am I over-indexing on [one group/venue/methodology]?"
- ### Step 8: Generate artifacts from NLM Studio (optional)
- ```
- studio_create(notebook_id=<id>, artifact_type="report") # or "slide_deck"
- download_artifact(notebook_id=<id>, artifact_type="report", output_path="synthesis/nlm_report.md")
- ```
- These are starting points — the student edits locally.
- ---
- ## Cross-Cutting: Expand — "Should this corpus grow?"
- **Purpose:** Structured, student-in-the-loop corpus expansion. Triggers at transition points between modes, not mid-reading.
- ### When candidates emerge
- - **During triage:** Frequently-cited references not in corpus → reason=FOUNDATIONAL
- - **During deepen:** Dependencies the student hasn't read → reason=DEPENDENCY
- - **During synthesize:** Entire sub-areas missing → reason=GAP_FILL
- - Papers that challenge existing corpus → reason=COUNTER
- - Adjacent community working on same problem → reason=ADJACENT
- ### The proposal workflow
- Batch candidates and present at transition points with:
- | Paper | Source of discovery | Reason | Relevance to intent | Suggested pass | Time cost |
- |-------|-------------------|--------|---------------------|---------------|-----------|
- For each, the student chooses:
- - **Add** → `source_add` to NLM notebook, download PDF locally, create paper note with Pass 1, update `corpus_log.md`
- - **Bookmark** → save to `backlog.md` for future surveys
- - **Skip** → log the reason (especially important for COUNTER papers)
- ### Budget guard
- Track expansion against the intent profile's scope and time budget. If corpus outgrows the plan:
- > "You started targeting ~30 papers. You're at 42. Your remaining time budget supports deepening ~5 more. Adjust scope or be more selective?"
- For Validators: conservative expansion. For Examiners: more permissive with diminishing-returns reasoning.
- ### Discovery via NLM research
- For Explorers and Examiners:
- ```
- research_start(query="[topic-specific search]", source="web", mode="deep", title="<topic>-expansion")
- research_status(notebook_id=<research_id>, max_wait=300)
- # Present discovered papers through the expand proposal workflow
- research_import(notebook_id=<survey_id>, task_id=<task_id>, source_indices=[student-approved])
- ```
- ---
- ## Session Continuity
- When a student returns after time away:
- 1. Read their local files: `survey_intent.md` (why), `survey_triage.md` (landscape), `corpus_log.md` (what's in the corpus), `papers/*.md` (what's been read).
- 2. Read `nlm_config.md` to reconnect to the NLM notebook.
- 3. Check which papers need deeper reading (marked Pass 2/3 in triage but no `[Pass 2]` section in paper note).
- 4. Resume from where they left off.
- The student's state is reconstructed from local files, not from NLM. If the NLM notebook were deleted, only query capability is lost — not the knowledge base.
- ---
- ## Reference Files
- Read these when deeper guidance is needed:
- | When you need... | Read this file |
- |---|---|
- | Keshav's three-pass method details | `reference/keshav_three_pass.md` |
- | Kahneman biases relevant to surveys | `reference/kahneman_biases.md` |
- | First-principles invariant questions | `reference/first_principles.md` |
- | NotebookLM MCP tool reference | `reference/notebooklm_tools.md` |
- | Six-move intro formula + craft questions | `reference/writing_craft_moves.md` |
- | Figure analysis guide + quality checklist | `reference/viz_analysis_guide.md` |
- | Survey intent template | `templates/survey_intent_template.md` |
- | Paper note template | `templates/paper_note_template.md` |
- | Triage template | `templates/survey_triage_template.md` |
- | Synthesis template | `templates/synthesis_template.md` |
README.md · README · 235 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # literature-survey-skill
- PhD students spend weeks on literature surveys. Most of that time is plumbing — finding papers, extracting claims, cross-referencing terminology, building comparison tables, chasing citation chains. The intellectual work that matters — spotting shared assumptions, finding where they break, recognizing the gap nobody has exploited — takes a fraction of the effort but only happens after the student is already exhausted from logistics.
- This skill offloads the plumbing to the machine. NotebookLM ingests your papers and returns grounded extractions with exact quotes. Claude Code manages the workflow — structured queries, template population, reading-depth tracking. You focus on forming hypotheses, deciding what matters, and building the narrative. The skill doesn't just save time; it makes you sharper. Every checkpoint — calibration protocols, WYSIATI checks, first-principles decomposition — forces you to articulate your understanding and confront where it falls short.
- **Who this is for:** PhD students and researchers running literature surveys of 10-150+ papers. Tuned for systems and networking (SIGCOMM, NSDI, CoNEXT, IMC) but adaptable to any field — see [Customize for Your Field](#customize-for-your-field).
- Built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
- ## Quick Start
- ```bash
- git clone https://github.com/SNL-UCSB/literature-survey-skill.git
- cd literature-survey-skill
- ./setup.sh
- ```
- This installs the skill to `~/.claude/skills/survey/`. Four commands become available:
- ```
- /survey intent — Capture your goals, expertise, and survey archetype
- /survey triage — Map the landscape, prioritize reading depth
- /survey deepen — Structured deep reading with craft and visualization extraction
- /survey synthesize — Cross-paper analysis for your deliverable
- /survey expand — Propose and evaluate corpus growth
- ```
- Start with `/survey intent`. The skill guides you from there.
- ### Prerequisites
- The [NotebookLM MCP CLI](https://github.com/jacob-bd/notebooklm-mcp-cli) must be configured as an MCP server in your Claude Code setup. **[Follow the setup guide](NOTEBOOKLM_SETUP.md)** — it covers installation, Google authentication, and MCP registration in ~5 minutes.
- ### Manual Install
- Copy `SKILL.md` to `~/.claude/skills/survey/SKILL.md`. Copy `reference/` and `templates/` alongside it.
- ## How Each Mode Works
- ### Intent — "What are you trying to learn?"
- The skill captures your goals, expertise level, and success criteria before any paper is read. It assigns one of four survey archetypes with calibrated defaults:
- | Archetype | When to use | Corpus | Pass 3 papers | Output |
- |-----------|------------|--------|---------------|--------|
- | Explorer | Entering a new area | 50-100+ | 2-3 | Landscape overview |
- | Investigator | Specific questions to answer | 10-25 | 3-5 | Technique comparison |
- | Validator | Confirming a gap or idea | 15-30 | 3-5 | Positioning argument |
- | Examiner | Exam or survey paper | 80-150+ | 5-8 | Full narrative survey |
- Your initial mental model is recorded verbatim. After triage, you compare it against what the corpus actually shows. The delta is where learning happens.
- ### Triage — "What's in this pile?"
- Triage builds the landscape map. The skill ingests papers into NotebookLM and generates per-paper summaries: category, problem, quoted contribution, evaluation, key references. It groups papers by thread and methodology, then runs a WYSIATI check — "what problem areas have zero papers?" It compares the landscape against your initial mental model from Intent, making anchoring effects visible. Finally, it prioritizes reading depth against your time budget.
- ### Deepen — "What does this paper really say?"
- Structured Pass 2 and Pass 3 for individual papers. Each pass adds layers to a growing paper note:
- - **Pass 2**: Claim extraction with exact quotes, evidence audit with strength ratings, methodology probing ("what breaks if the workload changes?"), dependency mapping.
- - **Calibration**: You write your one-sentence summary *before* seeing NLM's grounded extraction. The specificity gap between the two is the learning signal.
- - **First-principles**: State, Time, Coordination, Interface decomposition — forcing cross-paper comparability on fundamental dimensions.
- - **Pass 3**: Virtual re-implementation. "If you built this from scratch with the same goals, what would your design look like?"
- - **Writing craft extraction** (Pass 3+): Introduction anatomy using the six-move formula (Stakes → Problem Gap → Key Abstraction → Design Intuition → Contributions → Results Preview), evaluation architecture, design section craft, related work positioning.
- - **Visualization extraction** (Pass 2+): Figure inventory, visual argument analysis using WALTER, best-practice capture.
- A paper at Pass 1 produces a one-paragraph note. The same paper at Pass 3+ produces claims, evidence audits, first-principles decomposition, writing craft patterns, and visualization analysis — all in one file.
- ### Synthesize — "What connects all of this?"
- Synthesize produces cross-paper analysis for a specific deliverable. The skill builds three structures: an invariant matrix (papers compared on fundamental dimensions), a dependency graph (where one paper's design depends on an assumption another paper challenges), and a gap analysis (constraint-change reasoning, missing quadrants, methodology gaps). Output depends on the goal — related work sections with thematic arcs, area exam presentations, gap analyses, or new research directions.
- ### Expand — "Should this corpus grow?"
- Structured corpus growth with student-in-the-loop approval. Candidates surface during triage (foundational references cited in 3+ papers), deepen (dependencies the student hasn't read), and synthesize (entire sub-areas missing from the corpus). Each candidate comes with justification and time cost. A budget guard alerts when expansion outgrows the plan.
- ## What's in This Repo
- ```
- literature-survey-skill/
- ├── SKILL.md # The skill definition (install this)
- ├── README.md # You are here
- ├── NOTEBOOKLM_SETUP.md # NotebookLM MCP CLI setup guide
- ├── setup.sh # One-command install script
- ├── .gitignore
- ├── reference/
- │ ├── keshav_three_pass.md # Three-pass reading method with decision points
- │ ├── kahneman_biases.md # System 1/System 2 biases and countermeasures
- │ ├── first_principles.md # Invariant questions and design principles
- │ ├── notebooklm_tools.md # NLM MCP CLI tool reference and query patterns
- │ ├── writing_craft_moves.md # Six-move intro formula + evaluation/design craft
- │ └── viz_analysis_guide.md # Figure analysis, WALTER assessment, quality checklist
- └── templates/
- ├── survey_intent_template.md # Archetype, expertise, success criteria
- ├── paper_note_template.md # Growing paper note: Pass 1 → Craft → Viz
- ├── survey_triage_template.md # Landscape map, WYSIATI check, reading priorities
- └── synthesis_template.md # Invariant matrix, dependency graph, gap analysis
- ```
- ### Reference Files
- Six files providing targeted guidance for specific aspects of the workflow.
- `keshav_three_pass.md` covers the three-pass reading method with decision criteria for depth allocation and time estimates per pass level. `kahneman_biases.md` covers the five biases most dangerous during surveys — WYSIATI, Anchoring, Availability, Substitution, Illusion of Validity — with structural countermeasures baked into the workflow.
- `first_principles.md` covers the four invariant questions (State, Time, Coordination, Interface), three design principles, and Anchored Dependency Graph construction. `notebooklm_tools.md` covers the full NLM MCP CLI tool reference with query pattern templates organized by survey mode.
- `writing_craft_moves.md` covers the six-move introduction formula, evaluation architecture analysis, design section craft, and related work positioning strategy. `viz_analysis_guide.md` covers figure inventory, visual argument analysis, WALTER assessment, and quality checklists for honest representation.
- ### Templates
- Four templates that grow during a survey. `survey_intent_template.md` captures archetype, expertise baseline, and success criteria. `paper_note_template.md` structures the growing paper note from Pass 1 through craft and visualization extraction. `survey_triage_template.md` structures landscape maps, WYSIATI checks, and prioritized reading lists. `synthesis_template.md` structures invariant matrices, dependency graphs, and gap analyses.
- ### Use These Templates Without Claude Code
- The reference materials and templates work independently of the skill runtime. Use `paper_note_template.md` as a reading note structure in Obsidian or any markdown editor. Use `writing_craft_moves.md` as a framework for analyzing how papers communicate — print it out for lab reading groups. Use `synthesis_template.md` to structure cross-paper analysis manually. Use `viz_analysis_guide.md` and the WALTER principle for figure analysis in lab meetings.
- ---
- ## Why This Skill Exists
- Academic research faces a structural squeeze. Stagnant funding collides with rising costs. The arithmetic is stark: researchers must produce more with less, or momentum falters. Agentic AI systems offer a way through — not by replacing researchers, but by compressing the operational middle of the research pipeline while keeping the intellectual work human. This is the argument laid out in [*Systems for Agents, Agents for Systems*](https://sites.cs.ucsb.edu/~arpitgupta/blog/systems-for-agents-agents-for-systems.html).
- The division is clean. Three competencies remain structurally human: **discrimination** (evaluating what agents produce), **critique** (understanding failure modes), and **framing** (hypothesis formation and interpretation). Everything else — the mechanical logistics that exhaust students before they reach synthesis — is plumbing that machines can handle.
- Literature surveys are where this principle hits hardest. A student with a sharp research question and a pile of 50 papers has the ideation. What they lack is an efficient path from that question to a synthesized understanding they can build on. They spend weeks on extraction and cross-referencing, arrive at synthesis anchored by whatever they happened to read first, and mistake a fluent annotated bibliography for genuine understanding. The skill provides the path. The student walks it.
- The concern that agents weaken intellectual muscles gets the causality backwards. This skill doesn't hand students conclusions — it forces them to articulate their own understanding at every checkpoint and confront where it falls short. The calibration protocol, the WYSIATI checks, the first-principles decomposition — these are structural demands on the student's judgment. The machine provides raw material. The student provides discrimination, critique, and framing. The result is a student who reaches synthesis faster and arrives sharper, not one who skipped the thinking.
- ## Part of a Series
- This skill is one of a family of Claude Code skills developed at the [Systems and Networking Lab (SNL)](https://github.com/SNL-UCSB) at UC Santa Barbara by [Arpit Gupta](https://sites.cs.ucsb.edu/~arpitgupta/), each targeting a different phase of the research pipeline where plumbing buries ingenuity:
- | Skill | What it compresses | Student retains |
- |-------|-------------------|-----------------|
- | **[literature-survey-skill](https://github.com/SNL-UCSB/literature-survey-skill)** | Paper ingestion, claim extraction, cross-referencing, landscape mapping | Hypothesis formation, assumption identification, gap recognition, narrative construction |
- | **[data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill)** | Plot formatting, code generation, style compliance | Deciding what to show, why it matters, and whether the figure is honest |
- | **[paper-writing-skill](https://github.com/SNL-UCSB/paper-writing-skill)** | Drafting mechanics, structural scaffolding, revision logistics | Argument construction, positioning, voice |
- The principle is the same across all three: bridge the gap between ideation and execution. Compress the operational middle. Protect the thinking. The skills are independent — use any one alone — but they share an intellectual foundation and reinforce each other when used together. A literature survey feeds directly into a paper's related work section and its figures.
- ## Intellectual Foundations
- ### Kahneman's Dual-Process Theory
- System 1 (fast, intuitive, pattern-matching) and System 2 (slow, deliberate, analytical) explain why surveys fail in predictable ways.
- System 1 is efficient for triage. "This paper is relevant, this one isn't" is a fast pattern-match, and it works. System 1 becomes dangerous at synthesis. It substitutes easy questions for hard ones — "What is this paper about?" replaces "What assumption does this paper share with that one, and when does it break?" The student produces a fluent annotated bibliography and mistakes it for synthesis.
- Five biases are operationally relevant. WYSIATI (treating the current corpus as complete) is countered by explicit "what's missing?" checks at every mode transition. Anchoring (the first papers read frame everything) is countered by generating a landscape map before deep reading begins. Availability (recent or vivid papers dominate recall) is countered by the invariant matrix, which forces comparison across all papers on the same dimensions. Substitution (easy questions replacing hard ones) is countered by structured prompts that ask the hard question directly. The Illusion of Validity (coherent narrative masking incompleteness) is countered by the calibration protocol — student summary versus NLM grounded extraction, side by side.
- Every countermeasure is structural, not advisory. The landscape map breaks anchoring. The calibration protocol surfaces the specificity gap. The WYSIATI check makes absence visible. The workflow embeds the fix — the student never has to remember to apply it.
- ### Keshav's Three-Pass Reading Method
- Keshav's method allocates reading depth systematically. Pass 1 (5-10 minutes) covers title, abstract, headings, and conclusions — enough to decide if the paper merits more time. Pass 2 (~1 hour) grasps content without details: evidence and arguments, not proofs. Pass 3 (4-5 hours) is virtual re-implementation. Understand every assumption. Identify every limitation.
- The skill extends Pass 3 with two dimensions Keshav's original omits: writing craft extraction and visualization extraction. A well-written paper at Pass 3 rewards analysis of *how* it communicates, not just *what*. The six-move introduction formula, evaluation architecture patterns, and figure design choices extracted during deep reading feed directly into the student's own writing.
- ### First-Principles Systems Analysis
- Four invariant questions cut through surface differences between papers to reveal fundamental design choices. Developed at the [Systems and Networking Lab (SNL)](https://github.com/SNL-UCSB) at UC Santa Barbara and detailed in [*A First-Principles Approach to Networked Systems*](https://sites.cs.ucsb.edu/~arpitgupta/first-principles-networking/), they are: What state does the system manage? What timescales matter? How do components coordinate? What are the boundaries between components?
- These questions generate an invariant matrix — each row a paper, each column a fundamental dimension. Patterns, disagreements, and unexplored combinations become visible. The matrix is the raw material for a related work section built on structural comparison rather than chronological listing.
- ### NotebookLM as Grounded Query Backend
- NotebookLM serves as a query engine, not a knowledge store. Papers are ingested as sources. The student queries NLM for grounded extractions — exact quotes, cross-paper comparisons, passage identification. All intellectual artifacts (reading notes, synthesis documents, brainstorming sessions) live locally in the student's filesystem.
- This architecture is deliberate. If the NLM notebook were deleted, only query capability is lost. The student's accumulated understanding — captured in local markdown files — survives intact.
- ## Design Principles
- **Shunt the plumbing, protect the thinking.** The machine handles paper ingestion, claim extraction, cross-referencing, and template population. The student handles hypothesis formation, assumption identification, gap recognition, and narrative construction. The division is clean: logistics to the machine, judgment to the human.
- **Local-first architecture.** All intellectual artifacts live in the student's filesystem. NotebookLM holds paper sources and returns grounded answers. If NLM disappears, the student loses query capability — not the knowledge base.
- **Calibrated depth.** Not every paper deserves the same attention. The skill allocates reading depth based on the student's goals and the paper's role in the landscape — Pass 1 for background, Pass 2 for core threads, Pass 3 for foundational papers — with time budget tracking throughout.
- **Anti-bias by structure, not advice.** Every countermeasure is baked into the workflow. The landscape map breaks anchoring. The calibration protocol surfaces the specificity gap. The WYSIATI check makes absence visible. The invariant matrix prevents availability bias from distorting the narrative.
- **Growing notes.** Paper notes accumulate sections as reading deepens. A Pass 1 paper has a one-paragraph note. A Pass 3+ paper has claims, evidence audits, methodology analysis, first-principles decomposition, craft extraction, and visualization analysis — all in one file, all traceable.
- **Reading as writing practice.** Pass 3+ papers are analyzed for craft as well as content. The six-move introduction formula, evaluation architecture patterns, and visualization design choices extracted from well-written papers feed directly into the student's own writing skill. Reading and writing develop together.
- ## Customize for Your Field
- The skill ships with defaults tuned for systems and networking research (SIGCOMM, NSDI, CoNEXT, IMC). Five adaptation points:
- **First-principles questions.** Replace the four invariant questions (State, Time, Coordination, Interface) in `reference/first_principles.md` with dimensions fundamental to your field. ML: Data, Inductive Bias, Optimization, Generalization. Security: Threat Model, Trust Boundary, Mechanism, Usability.
- **Writing craft examples.** The six-move formula in `reference/writing_craft_moves.md` is venue-agnostic. The examples are from systems papers. Add examples from your field's best-written work.
- **Survey archetypes.** The four archetypes and their default paper counts are calibrated for CS PhD students. Adjust scope numbers for your field's publication rate and density.
- **NotebookLM prompts.** The query templates in `SKILL.md` use systems-specific terminology. Adapt for your domain vocabulary.
- **Visualization patterns.** The WALTER principle and figure analysis guide are domain-agnostic. Add field-specific encoding recommendations where needed (confusion matrices for ML, survival curves for clinical research, circuit diagrams for hardware).
- ## Intellectual Lineage
- | Source | Contribution | Where it appears |
- |--------|-------------|------------------|
- | Gupta, [*Systems for Agents, Agents for Systems*](https://sites.cs.ucsb.edu/~arpitgupta/blog/systems-for-agents-agents-for-systems.html) (2025) | Compress the operational middle, protect judgment | Design philosophy, skill series rationale |
- | Kahneman, *Thinking, Fast and Slow* (2011) | Dual-process theory, WYSIATI, anchoring, calibration | Every mode transition, calibration protocol, WYSIATI checks |
- | Keshav, "How to Read a Paper" (2007) | Three-pass reading, calibrated depth | Triage depth assignment, Deepen mode structure |
- | Gupta, [*A First-Principles Approach to Networked Systems*](https://sites.cs.ucsb.edu/~arpitgupta/first-principles-networking/) | Invariant questions (STCI), design principles, ADGs | Deepen Step 4, Synthesize invariant matrix |
- | [paper-writing-skill](https://github.com/SNL-UCSB/paper-writing-skill) | Six-move intro formula, evaluation maturity, design craft | Deepen Step 6, writing craft extraction |
- | [data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill) | WALTER principle, structured figure narration, visual argument analysis | Deepen Step 7, visualization extraction |
- | NotebookLM MCP CLI | Grounded query backend, source ingestion, cross-corpus queries | All modes (backend infrastructure) |
- | Tufte, *The Visual Display of Quantitative Information* (1983) | Data-ink ratio, honest representation | Visualization analysis guide |
- ## Contributing
- Contributions welcome. The highest-impact additions: domain-specific first-principles questions for fields beyond networking (ML, security, HCI, theory), example survey walkthroughs showing the full Intent → Triage → Deepen → Synthesize cycle on a real corpus, writing craft examples from venues beyond SIGCOMM/NSDI/IMC (NeurIPS, ICML, SOSP, OSDI, CHI), and integration patterns for reference managers (Zotero, Mendeley) and note-taking tools (Obsidian, Notion).
- ## License
- MIT
- ## Citation
- If you use this skill in your research workflow:
- ```
- @misc{literature-survey-skill,
- author = {Gupta, Arpit},
- title = {literature-survey-skill: A Claude Code skill for structured literature surveys},
- year = {2026},
- publisher = {GitHub},
- url = {https://github.com/SNL-UCSB/literature-survey-skill}
- }
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.