Lightweight profiles
Summarize one paper, or a set you picked, using the same machinery a full review uses — minus the review.
Same registry, same acquisition ladder, same extraction and appraisal prompts, same span verification. What is missing is everything that makes a review a review: no PRISMA flow, no effect-direction synthesis, no GRADE summary-of-findings table, no meta-analysis. That omission is the product, not a limitation to work around.
Which One Do I Want
| The ask | Use |
|---|---|
| "Summarize this paper", "what does this study say" — one PMID/DOI/PMCID/PDF | /deep-research:summarize |
| "Summarize these three", a small set you supply, or a bounded topic/question scan for candidates | /deep-research:summarize-set |
| Just get the structured data in — no write-up, no appraisal yet | /deep-research:extract |
| "What does the evidence say about X", "literature review", "systematic review" | The full pipeline — never these profiles |
| "What do my papers say about X" — answered from what the repo already holds | /deep-research:ask |
Single-Paper Summary
/deep-research:summarize --repo <repo> --pmid 12345678
/deep-research:summarize --repo <repo> --doi 10.1000/example
/deep-research:summarize --repo <repo> --pmcid PMC1234567
/deep-research:summarize --repo <repo> --pdf paper.pdf [--doi 10.1000/example]
/deep-research:summarize --repo <repo> --evidence-id pmid:12345678| Flag | Values | Effect |
|---|---|---|
--project | A project slug | Scopes the appraisal. Without it, an appraisal cannot be filed against a question |
--purpose | clinical, methods, journal-club, peer-review, background | Shapes framing and emphasis — never the evidence |
--audience | researcher, clinician, student, grant-writer, general | Register and assumed background |
--appraise / --no-appraise | On by default | Appraisal runs whenever full text and a supported framework are available |
--reuse / --no-reuse | Reuse by default | Whether to pull an existing extraction/appraisal from the pool |
--force | — | Regenerate even when reusable artifacts exist |
--format | md, html, both | Rendered output |
--offline | — | Local ladder rungs and reuse only; no network acquisition or discovery |
--title | Free text | Fallback for --pdf/--doi when metadata cannot be resolved |
How A Summary Actually Runs
paper.py never dispatches a subagent and never calls a model. It does the deterministic parts — registry lookup and registration, source acquisition, reuse, taskboard bookkeeping, rendering, verification — and returns a status telling the caller what to dispatch next. The agent dispatches it, the subagent writes its file, the same command is re-run, and it picks up from there.
Input paper
→ registry lookup or registration (registry.py — shared with the full pipeline)
→ source retrieval / PDF import (fulltext.py acquire — the same 9-rung ladder)
→ extraction reuse, or a new extraction task (one subagent, prompts/extract.md — Stage 5 verbatim)
→ appraisal reuse, or a new appraisal task (one subagent, prompts/appraise.md — Stage 6 verbatim,
project-scoped, on by default for full text)
→ summary assembly (one subagent, prompts/summarize-paper.md)
→ verification (verify.py single-paper-summary)
→ Markdown / HTML export
→ optional promotion of the extraction and appraisal back to the canonical poolReturned status | What the agent does next |
|---|---|
pending_retrieval | Resolve an MCP/browser ladder handoff, or ask you for the PDF |
pending_extraction | Dispatch the extraction prompt for this paper |
pending_appraisal | Dispatch the appraisal prompt against the verified extraction |
pending_summary | Dispatch the paper-summary prompt |
completed | Read the rendered Markdown/HTML |
failed | Read the error — it is quoted, not paraphrased |
Extraction Only (/deep-research:extract)
Fetches full text and produces a verified, promoted extraction — one paper or a bounded set — and stops there. No appraisal, no narrative summary, no Markdown/HTML export. It's the same acquisition ladder and the same Stage-5 extraction subagent as above, cut off one stage earlier.
/deep-research:extract --repo <repo> --pmid 12345678
/deep-research:extract --repo <repo> --pmid 123 --pmid 456 --pmid 789
/deep-research:extract --repo <repo> --folder papers/ --recursive
/deep-research:extract --repo <repo> --question "does exercise reduce depressive symptoms?" --limit 10same as summarize — reused if already registered
the same acquisition ladder
Stage-5 subagent, span-verified
extraction_status: extracted — no appraisal, no summary
Use it when the only goal right now is a paper's data/papers/extractions/ record — feeding search --q, ask, or a later okf-export — and nothing downstream needs an appraisal or a reader-facing write-up yet. Run /deep-research:summarize or summarize-set afterward whenever that changes: reuse picks the extraction straight back up, nothing is redone.
summarize, wider than pool-add. /deep-research:pool-add never touches full text — bibliographic metadata only. /deep-research:extract fetches and structures the paper's content but writes no narrative and no judgement. /deep-research:summarize/summarize-set do all of it. Same registry record either way — each command just carries it one stage further.
What A Summary Contains
Fourteen sections. Every sentence in §1–§12 must trace to a claim in the extraction or appraisal record — never to background knowledge.
| § | Section | Rule |
|---|---|---|
| 1 | Citation | — |
| 2 | Bottom line | ≤120 words. What the paper found, in the paper's own terms, with its own uncertainty |
| 3 | Why this paper was summarized | — |
| 4 | Study design and evidence basis | States fulltext or abstract_only. Abstract-only adds a plain statement that conduct could not be appraised |
| 5 | Population, setting, sample | — |
| 6 | Intervention / exposure / index test / model | Inapplicable fields say "not applicable to this design" rather than sitting blank |
| 7 | Comparator or reference standard | — |
| 8 | Outcomes and main results | One block per extracted outcome, with its effect, interval, and direction exactly as extracted — never re-rounded, never re-interpreted |
| 9 | Methods quality and risk of bias | If appraisal was skipped, this section names the reason: --no-appraise, abstract-only, or no supported tool. It is never silently omitted |
| 10 | Limitations | — |
| 11 | Practical takeaways | Only what the paper supports, labelled as single-study evidence. No recommendation beyond the paper's own discussion |
| 12 | What not to conclude from this paper alone | At least one bullet for any full-text clinical or journal-club summary |
| 13 | Provenance | Evidence id, extraction path, appraisal path or skip reason, generation time, verification status |
| 14 | Personal notes | Your own tags/rating/note from annotations.jsonl. Unverified — never cited as evidence, and never allowed to inform §1–§12 |
The frontmatter carries status: final or provisional — provisional whenever any verifier check failed — and the body opens with a standing banner: "This summarizes one paper, not a body of evidence."
Selected-Paper Sets
/deep-research:summarize-set --repo <repo> --pmid 123 --pmid 456 --overview
/deep-research:summarize-set --repo <repo> --ids-file papers.txt
/deep-research:summarize-set --repo <repo> --bib refs.bib
/deep-research:summarize-set --repo <repo> --folder papers/ --recursive
/deep-research:summarize-set --repo <repo> --question "..." --limit 10 --select-only
/deep-research:summarize-set --repo <repo> --topic "..." --limit 10The per-paper path is identical, run once per identifier. Partial failures are recorded rather than fatal — unresolved identifiers land in failed_identifiers with the stage they failed at, and appear in the set document.
| Mode | How the set is chosen |
|---|---|
explicit | Identifiers normalized and registered one by one, or via import-bib / import-folder for --bib / --folder |
question / topic | One bounded PubMed search, --limit-capped with a hard default when omitted. selection_basis records the query, database, timestamp, and limit |
--select-only stops after selection so you can inspect the picked set before paying for summaries.
The set document
| § | Section |
|---|---|
| 1 | Set description |
| 2 | Selection basis and limits — for discovery modes, labelled "bounded candidate discovery, not a systematic search" |
| 3 | Papers included: evidence id, title, design, appraisal — plus any failed identifiers |
| 4 | Optional overview, or "Not produced for this set." |
| 5 | Per-paper summaries, §1–§13 each, in the included order |
| 6 | Cross-paper cautions — a standing reminder, not a finding |
| 7 | Provenance |
Verification
python3 scripts/verify.py single-paper-summary \
--summary <run>/workspace/summaries/pmid-12345678.json --run-dir <run>
python3 scripts/verify.py paper-summary-set \
--summary-set <run>/workspace/summary-set.json --run-dir <run>Both write <run>/outputs/verification.json and check that:
- every claim resolves to the target paper's own
evidence_id; - every
span_refspointer resolves against the named extraction or appraisal file; - appraisal is present, or its skip reason is recorded;
- abstract-only summaries are labelled as such;
- no cross-study, pooled, or consensus wording appears outside a full-pipeline run.
A failure makes the summary provisional. The rendered output is still produced.
It Shares Everything With The Pipeline
There is no summary-only store. Both profiles read and write data/papers/registry.jsonl, data/papers/extractions/, and data/papers/appraisals/<project>/ — the same files a full review uses.
- A paper summarized today and later pulled into a review starts already registered, and possibly already extracted and appraised.
- A paper extracted during a review and later asked about individually reuses that extraction instead of re-running Stage 5.
- Because appraisal is project-scoped, an appraisal reused across projects is a deliberate choice you make with
--project, not an accident.