Transform academic PDFs into structured literature notes and critical-thinking canvases for Obsidian. Extracts PDFs, generates structured notes with Claude, and creates 9-node critical-thinking canvases.

version
0.2.2
GitHub stars
66

Install

/plugin install phd-deepread@phd-deepread

Run it inside Claude Code after adding the marketplace with /plugin marketplace add heleninsights-dot/phd-deepread-workflow.

Contents

Discovered from source

Skills 1

PhD Deep Read Workflow

Turn a PDF into three artifacts the user can drop straight into Obsidian:

  1. Extracted Markdown — full PDF text via PyMuPDF (fast path) with Tesseract OCR fallback for scanned pages.
  2. Structured literature note — YAML frontmatter, Dataview callouts, wikilinks, summary, critique, action items. You write this from the extracted text using the clauderules.md template.
  3. 9-node critical-thinking canvas — Obsidian Canvas JSON with core argument, assumptions, evidence, alternatives, methodological critique, personal relevance, future directions, critical questions, hypothesis center.

When to activate

The user shares an academic PDF — typically by dragging it into the chat or pasting a path — and asks for any of:

  • "phd-deepread read this paper" / "deep read this" / "read this and make a note"
  • "summarize this paper" / "give me a literature note"
  • "critique this" / "build a critical-thinking canvas"
  • "batch-process this folder of PDFs"

If they only want a quick summary (no Obsidian artifacts), this skill is overkill — answer directly instead.

How to run it

You drive the phd-deepread CLI on the user's behalf. The user does not type these commands.

Single paper (most common)

phd-deepread run /path/to/paper.pdf

This produces four things:

  • markdown_output/<paper>/<paper>.md — extracted text
  • A prompt file in structured_literature_notes/<paper>.md — this is a prompt, not a finished note
  • <paper>.canvas — blank 9-node template
  • A reformat prompt in structured_literature_notes/<paper>_reformat_prompt.md — also a prompt

You then write the literature note yourself. Read the prompt file, follow the instructions inside (it includes the full clauderules.md template), and overwrite the prompt file with the finished note. The prompt asks for tight YAML frontmatter, Dataview callouts, plain section headings (no emoji), extensive wikilinks, and academic tone — follow that exactly. Match examples/example-output.md.

Final reformat (makes the output look polished)

The raw extracted text (<paper>.md) is faithful but ugly — broken paragraphs, hyphenated line breaks, collapsed tables, page/header artifacts. To produce the clean reading copy users expect in Obsidian, run the reformat prompt:

phd-deepread reformat markdown_output/<paper>/ -o structured_literature_notes/<paper>_reformat_prompt.md

Then follow that prompt yourself: reflow paragraphs, dehyphenate, rebuild tables from the raw text, strip page/header artifacts, and collapse back-matter (references, abbreviations, declarations) into foldable callouts — writing the result to markdown_output/<paper>/<paper>_formatted.md. run emits this prompt automatically as its final step.

After the note is written, populate the canvas from it:

phd-deepread canvas -o markdown_output/<paper>/<paper>.canvas \
  --from-note structured_literature_notes/<paper>.md --overwrite

This maps note sections to canvas nodes by regex. Some nodes (assumptions, alternative-explanations) are auto-populated from related sections; the rest pull directly from the note. The user can refine any node in Obsidian.

Step by step (when the user wants control)

phd-deepread extract /path/to/paper.pdf            # PDF → markdown
phd-deepread generate markdown_output/<paper>/ -o notes/<paper>.md   # build prompt
phd-deepread canvas -o notes/<paper>.canvas --title "..." --authors "..." --year "..."

Batch a folder

phd-deepread batch /path/to/folder -o batch_output/ --create-canvases

Then loop over each <paper>_prompt.txt and write the finished note next to it.

Verifying output

phd-deepread verify markdown_output/<paper>/

Checks formatting, YAML frontmatter, callouts, wikilinks.

Templates

  • scripts/templates/clauderules.md — the literature-note template you must follow when writing the note. Loaded by generate.py via importlib.resources.
  • scripts/templates/reformat.md — the reformat instructions you follow in the final polish pass. Loaded by reformat.py via importlib.resources.
  • scripts/templates/critical-thinking.canvas — base canvas layout used by canvas.py.

Do not edit these as part of normal use.

Troubleshooting

  • "command not found: phd-deepread" — the package isn't installed or PATH is wrong. Run phd-deepread doctor (if available) or fall back to python3 -m pip install --user phd-deepread-workflow and tell the user to open a new terminal.
  • "Tesseract not found" — only matters for scanned (image-based) PDFs. Suggest brew install tesseract (macOS) or sudo apt install tesseract-ocr (Linux).
  • Template not found — package install incomplete; suggest pip install --upgrade phd-deepread-workflow.

Examples in this repo

  • examples/example-output.md — what a finished literature note looks like.
  • examples/example-canvas.canvas — what a populated canvas looks like.

Match those styles when writing your own.

Sponsors

Details

Marketplace
heleninsights-dot/phd-deepread-workflow
Author
Helen Insights
Category
Community