Expected Parrot · A practical, evidence-first tutorial

Build a literature review that remembers how it knows

Dewey helps a researcher and a coding agent find, screen, read, connect, and share scholarly literature without collapsing uncertain leads into evidence or losing the path by which a paper was found.

View Dewey on GitHub →Browse the worked review

Tool: DeweyLicense: MITRuntime: Python 3.11+Interface: CLI + portable HTML

The basic workflow

A review grows through distinct stages. Dewey keeps the boundary between them visible:

1Question

2Discover

3Screen

4Read

5Synthesize

Frame a research question before accumulating documents.
Put search results and references into a discovery queue.
Screen explicitly at title/abstract, full-text, and quantitative stages.
Preserve the accepted papers, rendered text, summaries, and notes.
Snowball selectively while retaining every discovery path.
Connect, audit, explore, and share the resulting review.

What Dewey does
Install Dewey
Start a review
Add anchor papers
Read and summarize
Traverse citations
Control duplicates
Screen candidates
Organize evidence
Prepare a meta-analysis
Explore the review
Share everything
Audit and resume
What Dewey stores
Research principles

01 What Dewey does

Dewey is a local workspace for a literature review. It is especially useful when a coding agent is helping: the durable record lives in files rather than chat history. The agent can inspect what exists, what remains unresolved, and what should happen next.

The central distinction is between a candidate and a source. A candidate is a potentially relevant work found through search, a bibliography, or manual entry. A source has been intentionally accepted into the managed corpus. Broad discovery therefore cannot silently become the evidence base.

Object	Meaning	Action
Candidate	A lead that may or may not belong	Screen it
Source	A managed document with stable identity	Read and summarize it
Provenance	Every route through which a work was found	Audit snowballing
Decision	A staged include, exclude, or maybe judgment	Record reason and reviewer
Link	A relationship between managed sources	Build citation and synthesis structure

02 Install Dewey

git clone https://github.com/expectedparrot/dewey.git
cd dewey
uv sync
uv run dewey --help

Or install the command globally:

uv tool install git+https://github.com/expectedparrot/dewey.git

Dewey uses paper2md for local PDF conversion. Firecrawl Parse is available when FIRECRAWL_API_KEY is in the environment or a local .env.

External-document warning. Firecrawl uploads the selected PDF and may consume paid credits. Do not use it for confidential or restricted material without authorization.

03 Start a review

Create an ordinary directory, initialize Dewey, and state the question. The question guides relevance scoring and gives later reviewers the intended scope.

mkdir ai-interviewers-review
cd ai-interviewers-review
dewey init
dewey topic set --topic "AI interviewers" \
  --question "How do AI interviewers affect data quality and respondent experience?"
dewey guide
dewey next

guide explains the lifecycle. next inspects current state and recommends the next action. Use both whenever a researcher or agent returns after time away.

04 Add anchor papers

Begin with a small, diverse set: a recent empirical study, a foundational method paper, and perhaps a review or adjacent application. Queue uncertain leads without pretending they passed screening.

dewey discover add --title "AI-Assisted Conversational Interviewing" \
  --author "Barari, Soubhik" --year 2025
dewey discover list --status candidate

If a PDF or BibTeX record is intentionally in scope, add it directly:

dewey add source paper.pdf
dewey add source citation.bib

05 Read, render, and summarize

Render PDF text before searching it or extracting references. Local conversion is the default.

dewey render md <source-id>
dewey cat <source-id> --representation md
dewey summary set <source-id> --text \
  "Randomized comparison of adaptive LLM probes and standardized questions. Reports richer answers with a modest experience cost."
dewey notes edit <source-id> --append \
  "Inspect appendix for exact group statistics."

A short summary should cover the question, method or evidence, main finding, and relevance. Put interpretation, quotations, caveats, and follow-up work in notes.

dewey render md <source-id> --backend firecrawl

Use the cloud backend only when upload has been authorized.

06 Traverse citations without losing the trail

After reading a relevant paper, extract its own bibliography. References become candidates, not automatically accepted sources.

dewey traverse references <source-id>
dewey discover list --status candidate

Each sighting records its parent source, raw citation, discovery method, and time. If three papers cite the same work, Dewey keeps one work with three provenance records.

Snowballing heuristic. Prefer references that supply a missing comparison, outcome, population, method, or historical predecessor. Stop a branch when it repeatedly yields already-known or out-of-scope work.

07 Control duplicate works

Citation strings vary. Dewey reconciles sightings using normalized DOI, arXiv ID, and conservative title identity. Audit before applying a bulk merge:

dewey discover dedupe --json
dewey discover dedupe --apply
dewey doctor

Merging retains the oldest candidate ID, richer metadata, current screening state, and all provenance. Uncertain probable duplicates remain separate for human review.

08 Screen candidates explicitly

Screening is independent of reading state. Record decisions at title/abstract, full-text, and quantitative-eligibility stages.

dewey screen decide <candidate-id> \
  --stage title-abstract --decision include \
  --reviewer jh --protocol-version v1 \
  --criterion population=yes --criterion comparator=unclear \
  --rationale "Potential controlled comparison; retrieve full text."

dewey screen decide <candidate-id> \
  --stage full-text --decision exclude --reason no-comparator \
  --reviewer jh --rationale "Descriptive deployment study only."

Exclusions require a controlled reason. Decisions are append-only, so corrections do not erase history.

dewey screen history <candidate-id>
dewey screen conflicts
dewey screen audit
dewey discover accept <candidate-id>

09 Organize the evidence

Reading status, summaries, notes, and links answer different questions. Keep them separate.

dewey state set <source-id> reading
dewey state set <source-id> included
dewey link add <later-source> <earlier-source> --type cites
dewey link add <source-a> <source-b> --type contradicts \
  --note "Opposite respondent-burden finding."
dewey order add <source-id>
dewey index rebuild
dewey search "respondent burden"

Citation links describe lineage. Synthesis links such as contradicts, uses_method, and builds_on preserve relationships that matter to the argument.

10 Prepare a meta-analysis

Quantitative eligibility is stricter than narrative relevance. Record whether a paper supplies an eligible comparison and calculable outcome.

dewey screen decide <candidate-id> \
  --stage quantitative-eligibility --decision include \
  --criterion randomized=yes --criterion comparator=yes \
  --criterion calculable-effect=yes --protocol-version v1

Prespecify population, intervention, comparator, outcomes, designs, effect direction, multiple-outcome handling, and dependence assumptions. Keep effects from a shared sample linked.

Current boundary. Native validated effect-size records are under development. Until then, keep a versioned extraction table in the project and cite page, table, figure, or supplement locations for every value.

11 Explore the review in a browser

dewey export html --output literature-explorer.html
open literature-explorer.html

The self-contained explorer includes the corpus, summaries, notes, rendered Markdown, discovery candidates, provenance counts, downloadable BibTeX, and an interactive chronological citation diagram. It is a snapshot; rebuild it after changes.

12 Share the complete project

The explorer is for reading. A Dewey ZIP is the transferable research workspace.

dewey export zip
dewey export zip --output ai-interviewers-review.dewey.zip

The archive contains managed PDFs, Markdown, summaries, notes, metadata, discovery and screening history, links, analyses, and browser exports in one folder. Its manifest records paths, sizes, and SHA-256 checksums. Git data, caches, symlinks, prior archives, and .env are omitted.

13 Audit and resume safely

dewey status
dewey doctor
dewey screen audit
dewey screen conflicts
dewey next

status distinguishes unique candidate works from discovery sightings. doctor checks repository consistency and exact duplicates. Screening audit finds incomplete decisions; conflicts expose different reviewer decisions at the same stage.

14 What Dewey stores

review/
├── .dewey/
│   ├── config.json
│   ├── discovery.json
│   ├── instructions.md
│   ├── review_order.json
│   ├── logs/activity.jsonl
│   ├── indexes/search.sqlite
│   └── sources/src_.../
│       ├── entry.bib
│       ├── metadata.json
│       ├── state.json
│       ├── source.pdf
│       ├── source.md
│       ├── summary.txt
│       ├── notes.md
│       └── links.json
├── literature-explorer.html
└── analysis files

Stable source IDs connect notes, links, citations, and commands. The index and explorer are derived; source records, decisions, provenance, notes, and summaries are durable review state.

15 Research principles

A lead is not evidence. Screen before accepting.
Absence is not a null result. Record inaccessible or uncertain evidence honestly.
Every judgment needs a trail. Keep reviewer, stage, reason, protocol, and provenance.
Every number needs a location. Record page, table, figure, supplement, or correspondence.
Duplicate records are not independent studies. Reconcile work identity and shared samples.
Automation proposes; researchers decide. Inspect conversion, references, screening, and synthesis.