Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/snl-ucsb--literature-survey-skill/badge.svg)](/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

i

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)

  1. ---
  2. name: survey
  3. 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."
  4. ---
  5. # Literature Survey Skill — Intent → Triage → Deepen → Synthesize
  6. 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.
  7. **Architecture:** All student work lives locally (Obsidian/filesystem). NotebookLM is a query backend only — papers go in, grounded answers come out.
  8. **Modes:**
  9. - `/survey intent` — Capture what you're trying to learn and where you're starting from
  10. - `/survey triage` — Map the landscape, prioritize reading depth
  11. - `/survey deepen` — Structured reading with craft and visualization extraction
  12. - `/survey synthesize` — Cross-paper analysis for deliverables
  13. - `/survey expand` — Structured corpus growth proposals
  14. 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.
  15. **Prerequisites:** NotebookLM MCP CLI must be configured. See `reference/notebooklm_tools.md` for setup.
  16. ---
  17. ## Mode 1: Intent — "What are you trying to learn?"
  18. **Purpose:** Capture the student's survey goals, expertise level, and success criteria BEFORE any paper is read. This shapes all subsequent modes.
  19. **Do NOT create any NotebookLM notebooks in this mode. Do NOT ingest any papers. The goal is purely clarifying intent.**
  20. ### Step 1: Identify the survey archetype
  21. Ask the student which best describes their situation:
  22. > Before we look at any papers, I need to understand what kind of survey this is. Which best describes you?
  23. >
  24. > **A. Explorer** — "I'm entering a new area and need to understand the landscape."
  25. > **B. Investigator** — "I have specific questions I need answered from the literature."
  26. > **C. Validator** — "I think I've found a gap/idea and want to confirm it's novel."
  27. > **D. Examiner** — "I need to demonstrate comprehensive mastery for an exam or survey paper."
  28. Each archetype has different defaults:
  29. | Archetype | Triage scope | Deepen targets | Pass 3 count | Synthesize output |
  30. |-----------|-------------|----------------|-------------|-------------------|
  31. | Explorer | 50-100+ papers | 8-15 at Pass 2 | 2-3 | Landscape overview |
  32. | Investigator | 10-25 papers | 5-10 at Pass 2 | 3-5 | Technique comparison |
  33. | Validator | 15-30 papers | 3-5 closest at Pass 2+3 | 3-5 | Positioning argument |
  34. | Examiner | 80-150+ papers | 15-25 at Pass 2 | 5-8 | Full narrative survey |
  35. ### Step 2: Assess expertise level
  36. Ask calibration questions for the chosen topic:
  37. > 1. **Vocabulary check:** Can you name 3 key technical terms in this area and define each in one sentence?
  38. > 2. **Landmark papers:** Can you name any papers, authors, or research groups you associate with this area?
  39. > 3. **Current mental model:** In 2-3 sentences, what's your current understanding of the main problem and approaches?
  40. > 4. **Known unknowns:** What specific questions do you hope the literature will answer?
  41. **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.
  42. ### Step 3: Define success criteria
  43. > 1. **Deliverable:** Related work section? Area exam presentation? Gap analysis? Idea validation?
  44. > 2. **Scope:** Approximately how many papers do you expect to cover?
  45. > 3. **Timeline:** When do you need the output?
  46. > 4. **Time budget:** How many hours per week can you invest?
  47. ### Step 4: Check for advisor input
  48. > Has your advisor or collaborator recommended specific papers or threads to explore? Any "must-read" papers with suggested reading depth?
  49. ### Step 5: Generate the intent profile
  50. Write a `survey_intent.md` file using the template from `templates/survey_intent_template.md`. Save it to the student's survey directory:
  51. ```
  52. literature-survey/surveys/<topic-slug>/survey_intent.md
  53. ```
  54. Also create the directory structure:
  55. ```
  56. surveys/<topic-slug>/
  57. ├── survey_intent.md
  58. ├── pdfs/
  59. ├── papers/
  60. │ └── figures/
  61. ├── synthesis/
  62. ├── corpus_log.md
  63. ├── backlog.md
  64. └── nlm_config.md
  65. ```
  66. Tell the student: "Your survey intent is captured. Run `/survey triage` when you're ready to start mapping the landscape."
  67. ---
  68. ## Mode 2: Triage — "What's in this pile?"
  69. **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.
  70. ### Step 1: Set up NotebookLM backend
  71. Read the student's `survey_intent.md` and `nlm_config.md`. If no notebook exists yet:
  72. ```
  73. notebook_create(title="survey-<topic-slug>")
  74. chat_configure(notebook_id=<id>, goal="custom",
  75. custom_prompt="You are a research corpus query engine for a PhD student
  76. surveying [topic]. The student is an [archetype] with goals: [from intent].
  77. Always cite specific papers and quote relevant passages.",
  78. response_length="longer")
  79. tag(action="add", notebook_id=<id>, tags=["survey", "<topic>", "<term>"])
  80. ```
  81. Save the notebook_id to `nlm_config.md`.
  82. ### Step 2: Seed the corpus
  83. Ask the student for their initial papers (PDFs, URLs, BibTeX). For each paper:
  84. 1. **Acquire the PDF locally** using the priority chain:
  85. - Student already has the file → copy to `pdfs/YYYY_author_shorttitle.pdf`
  86. - Open-access URL (Arxiv, university repo) → download via `wget`
  87. - Semantic Scholar API → query for open-access PDF URL
  88. - Prompt the student for upload or URL
  89. 2. **Ingest into NotebookLM** (async for large batches):
  90. ```
  91. source_add(notebook_id=<id>, source_type="file", file=<path>, wait=False)
  92. ```
  93. 3. **Log in `corpus_log.md`** with status "ingesting".
  94. 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.
  95. ### Step 3: Generate Pass 1 summaries
  96. Once sources are ready, for each paper query NLM:
  97. ```
  98. notebook_query(notebook_id=<id>,
  99. query="For [title] by [author]: provide CATEGORY (measurement/systems-building/theory/survey),
  100. PROBLEM (one sentence), CONTRIBUTION (exact quote of main claim), EVALUATION (system/dataset/testbed),
  101. KEY REFERENCES (3-5 most cited references), RELEVANCE to survey goals (high/medium/low)")
  102. ```
  103. Write each response to a local file: `papers/YYYY_author_shorttitle.md` with a `[Pass 1]` header.
  104. ### Step 4: Generate landscape map
  105. Query NLM for a cross-corpus landscape:
  106. ```
  107. notebook_query(notebook_id=<id>,
  108. query="Group all papers by PROBLEM addressed (3-5 major threads). For each thread, list papers
  109. and methodology. Identify chronological patterns. WYSIATI CHECK: What problem areas or
  110. methodologies are absent? What would a skeptical reviewer say is missing?")
  111. ```
  112. Write to `survey_triage.md`.
  113. ### Step 5: WYSIATI check and intent comparison
  114. **This is a System 2 checkpoint.** Show the student their initial mental model (from `survey_intent.md`) alongside the landscape map:
  115. > "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?"
  116. ### Step 6: Prioritize reading depth
  117. Help the student categorize each paper against their time budget:
  118. - **Pass 1 only** — background knowledge
  119. - **Pass 2 recommended** — relevant to core thread
  120. - **Pass 3 required** — foundational, must deeply understand
  121. Update `survey_triage.md` with the prioritized reading list.
  122. ### Step 7: Surface expansion candidates
  123. ```
  124. notebook_query(notebook_id=<id>,
  125. query="Which references appear in 3+ papers but are NOT sources in this notebook?
  126. For each, explain why it might be important to add.")
  127. ```
  128. Append candidates to `corpus_log.md` with reason=FOUNDATIONAL. Present to student for Add/Bookmark/Skip decision (see `/survey expand` protocol).
  129. ---
  130. ## Mode 3: Deepen — "What does this paper really say?"
  131. **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.
  132. ### Step 1: Select a paper
  133. Ask which paper from the triage reading list. Read their existing paper note if one exists.
  134. ### Step 2: Pass 2 protocol
  135. Run four NLM queries and write results to the local paper note:
  136. **a. Claim extraction:**
  137. ```
  138. notebook_query: "For [title]: Quote the 3 most important claims with section/page references."
  139. ```
  140. **b. Evidence audit:**
  141. ```
  142. notebook_query: "For [title]: For each claim, what evidence is provided? Rate as strong/moderate/weak."
  143. ```
  144. **c. Methodology probe:**
  145. ```
  146. notebook_query: "For [title]: Describe evaluation setup. What explicit and implicit assumptions?
  147. What would break if workload/scale/topology changed?"
  148. ```
  149. **d. Dependency extraction:**
  150. ```
  151. notebook_query: "For [title]: What results from other papers does this depend on?
  152. Which dependencies might not hold in other contexts?"
  153. ```
  154. Write all responses to the paper's local note as a `[Pass 2]` section.
  155. ### Step 3: Calibration check (System 2 prosthetic)
  156. After the student has read the paper themselves, compare their understanding with NLM's grounded extraction:
  157. 1. Ask the student: "In one sentence, what is this paper's main contribution?"
  158. 2. Query NLM: "Quote the exact main contribution claim from the abstract or introduction."
  159. 3. Show both side by side in a `[Calibration]` section. Highlight the specificity gap.
  160. ### Step 4: First-principles decomposition
  161. ```
  162. notebook_query: "For [title], analyze along four dimensions:
  163. STATE: What state does the system manage?
  164. TIME: What timescales matter?
  165. COORDINATION: How do components coordinate?
  166. INTERFACE: What are the boundaries between components?
  167. Quote specific passages as evidence."
  168. ```
  169. Write to the paper note as `[First-Principles]` section.
  170. ### Step 5: Pass 3 — Virtual re-implementation (foundational papers only)
  171. Ask the student:
  172. - "If you had to build this system from scratch with the same goals, what would your design look like?"
  173. - "What assumptions are never explicitly stated?"
  174. - "Write three critical questions a skeptical PC member would ask."
  175. ### Step 6: Writing craft extraction (Pass 3+ papers the student admires)
  176. Read `reference/writing_craft_moves.md` for the full framework. Query NLM and guide the student through:
  177. **a. Introduction anatomy — the six-move formula:**
  178. ```
  179. notebook_query: "For [title], analyze the INTRODUCTION:
  180. MOVE 1 (Stakes): How does it open? Specific actors/applications/dollar amounts?
  181. MOVE 2 (Problem Gap): Structural or quantitative? Numbered limitations?
  182. MOVE 3 (Key Abstraction): Does it coin a memorable, citable term?
  183. MOVE 4 (Design Intuition): One-paragraph mental model? Overview figure?
  184. MOVE 5 (Contributions): Claims with evidence, or process descriptions? Numbered?
  185. MOVE 6 (Results Preview): Concrete headline numbers?
  186. Quote specific passages."
  187. ```
  188. **b. Evaluation architecture:**
  189. ```
  190. notebook_query: "For [title], analyze the EVALUATION:
  191. CLAIM-EVIDENCE MAP: List every intro claim → evaluation subsection → figure/table.
  192. SETUP: Compressed or technical report?
  193. DEEP DIVE: Results disaggregated by meaningful dimensions?
  194. TAKEAWAYS: Explicit takeaway after every experiment cluster?
  195. ABLATION: Shows each component contributes?"
  196. ```
  197. **c. Design section craft:**
  198. ```
  199. notebook_query: "For [title], analyze the DESIGN:
  200. Opens with abstraction or implementation?
  201. 'Why' move — justification via negative result?
  202. Named components? Key configurable 'knob'?"
  203. ```
  204. **d. Related work positioning:**
  205. Ask the student: How many categories? Structural or quantitative limitations? Explicit positioning sentence?
  206. **e. Peak observation:** What is the single most memorable insight — the thing you'd cite 10 years from now?
  207. **f. Lessons for my writing:** The student captures what they want to adopt for their own papers.
  208. Write to paper note as `[Craft]` section. Also append key lessons to `synthesis/writing_craft_corpus.md`.
  209. ### Step 7: Visualization extraction (all Pass 2+ papers)
  210. Read `reference/viz_analysis_guide.md`. Query NLM and guide the student through:
  211. **a. Figure inventory:**
  212. ```
  213. notebook_query: "For [title]: List every figure and table. For each: caption, role
  214. (overview/comparison/deep-dive/ablation/case-study), claim it supports, encoding used.
  215. Which is the headline figure?"
  216. ```
  217. **b. Visual argument analysis (2-3 key figures):**
  218. ```
  219. notebook_query: "For [title], for the 2-3 most important figures:
  220. What claim does each support? Describe encoding choices (axes, scale, color, faceting).
  221. WHY those choices — does the encoding serve the argument?
  222. What does the figure NOT show that would be useful?"
  223. ```
  224. **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/`.
  225. Write to paper note as `[Visualization]` section. Append best-practice examples to `synthesis/viz_patterns.md`.
  226. ### Output
  227. The local paper note (`papers/YYYY_author_shorttitle.md`) grows through the mode:
  228. `[Pass 1]` → `[Pass 2]` → `[Calibration]` → `[First-Principles]` → `[Craft]` → `[Visualization]` → `[My Notes]`
  229. ---
  230. ## Mode 4: Synthesize — "What connects all of this?"
  231. **Purpose:** Cross-paper synthesis for a specific deliverable. Uses NLM cross-corpus queries, writes all results locally.
  232. ### Step 1: Select synthesis goal
  233. The student chooses (informed by their intent profile):
  234. - **Related work section** — organized thematic narrative
  235. - **Area exam presentation** — breadth + depth + frontier identification
  236. - **Research gap identification** — systematic analysis of what's missing
  237. - **New idea synthesis** — creative recombination of insights
  238. ### Step 2: Invariant matrix
  239. ```
  240. notebook_query: "For every paper, build a comparison matrix:
  241. State management | Primary timescale | Coordination model | Interface design.
  242. Highlight where papers make fundamentally different choices."
  243. ```
  244. Write to `synthesis/invariant_matrix.md`. Student annotates locally.
  245. ### Step 3: Dependency graph
  246. ```
  247. notebook_query: "Identify cases where one paper's design DEPENDS ON an assumption
  248. another paper challenges. Quote the assumption and the challenging evidence."
  249. ```
  250. Write to `synthesis/dependency_graph.md`.
  251. ### Step 4: Gap identification
  252. ```
  253. notebook_query: "If [bandwidth/latency/scale] changed by 10x, which solutions still work?
  254. Which break? What new problems emerge that no paper addresses?"
  255. ```
  256. Also ask: "Looking at the invariant matrix — are there combinations no paper explores? Missing methodologies?"
  257. Write to `synthesis/gap_analysis.md`.
  258. ### Step 5: Cross-survey synthesis (if multiple survey notebooks exist)
  259. ```
  260. cross_notebook_query(query="How do approaches to [dimension] differ between
  261. [survey A] and [survey B]?", tags=["survey"])
  262. ```
  263. ### Step 6: Narrative construction
  264. Based on the synthesis goal, generate the deliverable draft:
  265. - **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."
  266. - **Area exam:** Breadth across subfield + depth on 2-3 foundational papers + frontier identification + student's own position.
  267. - **Gap analysis:** Constraint-change analysis → candidate problems with first-principles justification.
  268. - **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]."
  269. ### Step 7: WYSIATI final audit
  270. Before finalizing:
  271. > "What perspectives are missing? What would someone from [adjacent field] say? Am I over-indexing on [one group/venue/methodology]?"
  272. ### Step 8: Generate artifacts from NLM Studio (optional)
  273. ```
  274. studio_create(notebook_id=<id>, artifact_type="report") # or "slide_deck"
  275. download_artifact(notebook_id=<id>, artifact_type="report", output_path="synthesis/nlm_report.md")
  276. ```
  277. These are starting points — the student edits locally.
  278. ---
  279. ## Cross-Cutting: Expand — "Should this corpus grow?"
  280. **Purpose:** Structured, student-in-the-loop corpus expansion. Triggers at transition points between modes, not mid-reading.
  281. ### When candidates emerge
  282. - **During triage:** Frequently-cited references not in corpus → reason=FOUNDATIONAL
  283. - **During deepen:** Dependencies the student hasn't read → reason=DEPENDENCY
  284. - **During synthesize:** Entire sub-areas missing → reason=GAP_FILL
  285. - Papers that challenge existing corpus → reason=COUNTER
  286. - Adjacent community working on same problem → reason=ADJACENT
  287. ### The proposal workflow
  288. Batch candidates and present at transition points with:
  289. | Paper | Source of discovery | Reason | Relevance to intent | Suggested pass | Time cost |
  290. |-------|-------------------|--------|---------------------|---------------|-----------|
  291. For each, the student chooses:
  292. - **Add** → `source_add` to NLM notebook, download PDF locally, create paper note with Pass 1, update `corpus_log.md`
  293. - **Bookmark** → save to `backlog.md` for future surveys
  294. - **Skip** → log the reason (especially important for COUNTER papers)
  295. ### Budget guard
  296. Track expansion against the intent profile's scope and time budget. If corpus outgrows the plan:
  297. > "You started targeting ~30 papers. You're at 42. Your remaining time budget supports deepening ~5 more. Adjust scope or be more selective?"
  298. For Validators: conservative expansion. For Examiners: more permissive with diminishing-returns reasoning.
  299. ### Discovery via NLM research
  300. For Explorers and Examiners:
  301. ```
  302. research_start(query="[topic-specific search]", source="web", mode="deep", title="<topic>-expansion")
  303. research_status(notebook_id=<research_id>, max_wait=300)
  304. # Present discovered papers through the expand proposal workflow
  305. research_import(notebook_id=<survey_id>, task_id=<task_id>, source_indices=[student-approved])
  306. ```
  307. ---
  308. ## Session Continuity
  309. When a student returns after time away:
  310. 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).
  311. 2. Read `nlm_config.md` to reconnect to the NLM notebook.
  312. 3. Check which papers need deeper reading (marked Pass 2/3 in triage but no `[Pass 2]` section in paper note).
  313. 4. Resume from where they left off.
  314. 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.
  315. ---
  316. ## Reference Files
  317. Read these when deeper guidance is needed:
  318. | When you need... | Read this file |
  319. |---|---|
  320. | Keshav's three-pass method details | `reference/keshav_three_pass.md` |
  321. | Kahneman biases relevant to surveys | `reference/kahneman_biases.md` |
  322. | First-principles invariant questions | `reference/first_principles.md` |
  323. | NotebookLM MCP tool reference | `reference/notebooklm_tools.md` |
  324. | Six-move intro formula + craft questions | `reference/writing_craft_moves.md` |
  325. | Figure analysis guide + quality checklist | `reference/viz_analysis_guide.md` |
  326. | Survey intent template | `templates/survey_intent_template.md` |
  327. | Paper note template | `templates/paper_note_template.md` |
  328. | Triage template | `templates/survey_triage_template.md` |
  329. | 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)

  1. # literature-survey-skill
  2. 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.
  3. 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.
  4. **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).
  5. Built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
  6. ## Quick Start
  7. ```bash
  8. git clone https://github.com/SNL-UCSB/literature-survey-skill.git
  9. cd literature-survey-skill
  10. ./setup.sh
  11. ```
  12. This installs the skill to `~/.claude/skills/survey/`. Four commands become available:
  13. ```
  14. /survey intent — Capture your goals, expertise, and survey archetype
  15. /survey triage — Map the landscape, prioritize reading depth
  16. /survey deepen — Structured deep reading with craft and visualization extraction
  17. /survey synthesize — Cross-paper analysis for your deliverable
  18. /survey expand — Propose and evaluate corpus growth
  19. ```
  20. Start with `/survey intent`. The skill guides you from there.
  21. ### Prerequisites
  22. 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.
  23. ### Manual Install
  24. Copy `SKILL.md` to `~/.claude/skills/survey/SKILL.md`. Copy `reference/` and `templates/` alongside it.
  25. ## How Each Mode Works
  26. ### Intent — "What are you trying to learn?"
  27. 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:
  28. | Archetype | When to use | Corpus | Pass 3 papers | Output |
  29. |-----------|------------|--------|---------------|--------|
  30. | Explorer | Entering a new area | 50-100+ | 2-3 | Landscape overview |
  31. | Investigator | Specific questions to answer | 10-25 | 3-5 | Technique comparison |
  32. | Validator | Confirming a gap or idea | 15-30 | 3-5 | Positioning argument |
  33. | Examiner | Exam or survey paper | 80-150+ | 5-8 | Full narrative survey |
  34. Your initial mental model is recorded verbatim. After triage, you compare it against what the corpus actually shows. The delta is where learning happens.
  35. ### Triage — "What's in this pile?"
  36. 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.
  37. ### Deepen — "What does this paper really say?"
  38. Structured Pass 2 and Pass 3 for individual papers. Each pass adds layers to a growing paper note:
  39. - **Pass 2**: Claim extraction with exact quotes, evidence audit with strength ratings, methodology probing ("what breaks if the workload changes?"), dependency mapping.
  40. - **Calibration**: You write your one-sentence summary *before* seeing NLM's grounded extraction. The specificity gap between the two is the learning signal.
  41. - **First-principles**: State, Time, Coordination, Interface decomposition — forcing cross-paper comparability on fundamental dimensions.
  42. - **Pass 3**: Virtual re-implementation. "If you built this from scratch with the same goals, what would your design look like?"
  43. - **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.
  44. - **Visualization extraction** (Pass 2+): Figure inventory, visual argument analysis using WALTER, best-practice capture.
  45. 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.
  46. ### Synthesize — "What connects all of this?"
  47. 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.
  48. ### Expand — "Should this corpus grow?"
  49. 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.
  50. ## What's in This Repo
  51. ```
  52. literature-survey-skill/
  53. ├── SKILL.md # The skill definition (install this)
  54. ├── README.md # You are here
  55. ├── NOTEBOOKLM_SETUP.md # NotebookLM MCP CLI setup guide
  56. ├── setup.sh # One-command install script
  57. ├── .gitignore
  58. ├── reference/
  59. │ ├── keshav_three_pass.md # Three-pass reading method with decision points
  60. │ ├── kahneman_biases.md # System 1/System 2 biases and countermeasures
  61. │ ├── first_principles.md # Invariant questions and design principles
  62. │ ├── notebooklm_tools.md # NLM MCP CLI tool reference and query patterns
  63. │ ├── writing_craft_moves.md # Six-move intro formula + evaluation/design craft
  64. │ └── viz_analysis_guide.md # Figure analysis, WALTER assessment, quality checklist
  65. └── templates/
  66. ├── survey_intent_template.md # Archetype, expertise, success criteria
  67. ├── paper_note_template.md # Growing paper note: Pass 1 → Craft → Viz
  68. ├── survey_triage_template.md # Landscape map, WYSIATI check, reading priorities
  69. └── synthesis_template.md # Invariant matrix, dependency graph, gap analysis
  70. ```
  71. ### Reference Files
  72. Six files providing targeted guidance for specific aspects of the workflow.
  73. `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.
  74. `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.
  75. `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.
  76. ### Templates
  77. 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.
  78. ### Use These Templates Without Claude Code
  79. 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.
  80. ---
  81. ## Why This Skill Exists
  82. 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).
  83. 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.
  84. 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.
  85. 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.
  86. ## Part of a Series
  87. 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:
  88. | Skill | What it compresses | Student retains |
  89. |-------|-------------------|-----------------|
  90. | **[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 |
  91. | **[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 |
  92. | **[paper-writing-skill](https://github.com/SNL-UCSB/paper-writing-skill)** | Drafting mechanics, structural scaffolding, revision logistics | Argument construction, positioning, voice |
  93. 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.
  94. ## Intellectual Foundations
  95. ### Kahneman's Dual-Process Theory
  96. System 1 (fast, intuitive, pattern-matching) and System 2 (slow, deliberate, analytical) explain why surveys fail in predictable ways.
  97. 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.
  98. 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.
  99. 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.
  100. ### Keshav's Three-Pass Reading Method
  101. 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.
  102. 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.
  103. ### First-Principles Systems Analysis
  104. 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?
  105. 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.
  106. ### NotebookLM as Grounded Query Backend
  107. 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.
  108. 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.
  109. ## Design Principles
  110. **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.
  111. **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.
  112. **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.
  113. **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.
  114. **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.
  115. **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.
  116. ## Customize for Your Field
  117. The skill ships with defaults tuned for systems and networking research (SIGCOMM, NSDI, CoNEXT, IMC). Five adaptation points:
  118. **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.
  119. **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.
  120. **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.
  121. **NotebookLM prompts.** The query templates in `SKILL.md` use systems-specific terminology. Adapt for your domain vocabulary.
  122. **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).
  123. ## Intellectual Lineage
  124. | Source | Contribution | Where it appears |
  125. |--------|-------------|------------------|
  126. | 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 |
  127. | Kahneman, *Thinking, Fast and Slow* (2011) | Dual-process theory, WYSIATI, anchoring, calibration | Every mode transition, calibration protocol, WYSIATI checks |
  128. | Keshav, "How to Read a Paper" (2007) | Three-pass reading, calibrated depth | Triage depth assignment, Deepen mode structure |
  129. | 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 |
  130. | [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 |
  131. | [data-visualization-skill](https://github.com/SNL-UCSB/data-visualization-skill) | WALTER principle, structured figure narration, visual argument analysis | Deepen Step 7, visualization extraction |
  132. | NotebookLM MCP CLI | Grounded query backend, source ingestion, cross-corpus queries | All modes (backend infrastructure) |
  133. | Tufte, *The Visual Display of Quantitative Information* (1983) | Data-ink ratio, honest representation | Visualization analysis guide |
  134. ## Contributing
  135. 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).
  136. ## License
  137. MIT
  138. ## Citation
  139. If you use this skill in your research workflow:
  140. ```
  141. @misc{literature-survey-skill,
  142. author = {Gupta, Arpit},
  143. title = {literature-survey-skill: A Claude Code skill for structured literature surveys},
  144. year = {2026},
  145. publisher = {GitHub},
  146. url = {https://github.com/SNL-UCSB/literature-survey-skill}
  147. }
  148. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.