pro-research

name	pro-research
description	Professional paper research with papercli. Multi-pass search, PDF download and reading, math-aware synthesis, and a detailed referenced markdown findings report.
homepage	https://github.com/jimezsa/papercli
metadata	{"opencolab":{"emoji":"📄","os":["linux","darwin"],"requires":{"bins":["papercli"]},"install":[{"id":"homebrew","kind":"shell","script":"brew install jimezsa/tap/papercli","bins":["papercli"],"label":"Install PaperCLI with Homebrew"},{"id":"source","kind":"shell","script":"git clone https://github.com/jimezsa/papercli.git && cd papercli && make build && sudo install -m 0755 ./bin/papercli /usr/local/bin/papercli","bins":["papercli"],"label":"Build PaperCLI from source"}]}}

Pro Research Skill

Use this skill when the user needs a serious literature synthesis, not a quick scan. This workflow prioritizes methodological depth, cross-paper comparison, and explicit evidence tracking.

If the user later asks an exact follow-up question about a downloaded paper or a bounded local paper subset, switch to pageindex-grounded for page-level grounded retrieval instead of forcing that work through the synthesis report alone.

Update This Skill

Only do this if the user explicitly asks to update this skill from the GitHub repo.

To refresh this skill directly from the GitHub repo:

curl -fsSL https://raw.githubusercontent.com/jimezsa/papercli/main/SKILLS/pro-research/SKILL.md \
  -o SKILLS/pro-research/SKILL.md

Mission

Answer a scientific question by building a medium-depth evidence base from papers retrieved with papercli, then deliver a detailed findings.md with:

• Core ideas and major concepts.
• Key mathematical formulations.
• Cross-paper agreements and disagreements.
• Explicit references for every non-trivial claim.
• A companion literature-map block diagram that shows how the main papers or paper families connect.
• A topic-scoped research run folder with maintained metadata so later agents can recognize and reuse the work.

Prerequisites

• papercli is installed and available in PATH.

Hard Requirements

• Retrieval must use papercli.
• Download and read the selected PDFs.
• Do not rely on abstract-only synthesis when full text is available.
• Every analytical paragraph must contain [R#] citations.
• Final deliverable is a detailed markdown file named findings.md inside the active research run folder.
• Each distinct topic must live in its own dated, topic-slugged folder under research/.
• Maintain research/INDEX.md and the run-local RUN.md metadata file so later agents can recognize what each research folder contains.
• After synthesis, produce a companion literature-map diagram through the shared block-diagram skill.
• The literature map must only show evidence-backed relations such as method lineage, direct comparison, shared benchmark or dataset, critique, or common problem framing.
• Do not invent paper-to-paper influence or citation edges that are not supported by the corpus.
• OpenColab normally provides OPENCOLAB_PROGRESS_FILE during provider runs. When it is set, emit bounded JSON progress updates for long-running stages instead of remaining silent until the end.

OpenColab Progress Helper

OpenColab exposes this progress channel by default during provider runs. When OPENCOLAB_PROGRESS_FILE is available, use this helper:

emit_progress() {
  if [ -z "${OPENCOLAB_PROGRESS_FILE:-}" ]; then
    return 0
  fi
  printf '%s\n' "$1" >> "$OPENCOLAB_PROGRESS_FILE"
}

Write one-line JSON events. Allowed kind values are started, progress, milestone, warning, needs_input, and completed.

Example:

emit_progress '{"kind":"progress","stage":"download","slot":"search","current":8,"total":12,"message":"Downloaded 8 of 12 PDFs."}'

Let the agent decide what is worth sending. Use progress for countable ongoing work, milestone for stage changes, warning for degraded runs, needs_input for blockers, and completed when an explicit completion event helps. Do not narrate every minor command.

Topic-Scoped Research Workspace

Every run must use an active run root:

• New topic: research/<YYYY-MM-DD>-<topic-slug>/.
• Topic slug: lowercase ASCII, hyphenated, 3-8 meaningful words, and specific enough to distinguish the topic from nearby research.
• Collision rule: if the folder exists for different work, append -2, -3, or another short disambiguator.
• Continuation rule: reuse an existing folder only when the user asks to continue the same topic or the folder clearly matches the current request.
• Root catalog: update research/INDEX.md when the run starts and again when it finishes, is blocked, or is left partial.
• Run metadata: create and update <RUN_ROOT>/RUN.md with topic, question, skill, status, created/updated timestamps, corpus counts, generated artifact paths, and follow-up notes.

Recommended research/INDEX.md columns:

| Folder | Skill | Topic | Status | Created | Updated | Corpus | Deliverables | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |

Recommended <RUN_ROOT>/RUN.md headings:

# Research Run: <topic>

## Metadata

- Skill: pro-research
- Status: in-progress
- Created:
- Updated:
- Topic slug:
- Question:

## Corpus

- Selected:
- Downloaded:
- Summarized:
- Failure events:

## Artifacts

- Findings:
- Literature map:
- Search files:
- Metadata:
- PDFs and summaries:

## Notes

Workflow

1. Define research frame

Extract:

• Main question.
• Scope boundaries (domain, years, task setting, constraints).
• Evaluation criteria (accuracy, sample efficiency, robustness, compute, interpretability, etc.).

2. Build query matrix and search

Run at least 3 query types:

1. Canonical problem phrasing.
2. Method-centric phrasing.
3. Recent trend phrasing.

TOPIC_SLUG="<topic-slug>"
RUN_ROOT="research/$(date +%F)-${TOPIC_SLUG}"
mkdir -p "$RUN_ROOT"/{search,meta,pdf,diagrams}
printf "stage\tid\treason\n" > "$RUN_ROOT/meta/failures.tsv"
: > "$RUN_ROOT/meta/downloaded_ids.txt"
: > "$RUN_ROOT/meta/summarized_ids.txt"

papercli search "<canonical query>" --provider all --sort relevance --limit 25 --format json --out "$RUN_ROOT/search/q1.json"
papercli search "<method query>"    --provider all --sort relevance --limit 25 --format json --out "$RUN_ROOT/search/q2.json"
papercli search "<trend query>"     --provider all --sort date --year-from <recent_year> --limit 25 --format json --out "$RUN_ROOT/search/q3.json"

Before retrieval, add or update the row for $RUN_ROOT in research/INDEX.md with status in-progress, and create or update $RUN_ROOT/RUN.md.

Optional author-centered expansion:

papercli author "<key author>" --provider all --sort relevance --limit 15 --format json --out "$RUN_ROOT/search/author.json"

3. Select 8-12 papers and enrich metadata

Selection rules:

• Include seminal plus recent papers.
• Include at least two competing approaches.
• Include at least one negative/critical or limitation-heavy paper when possible.

jq -r '.[].id' "$RUN_ROOT"/search/*.json | awk 'NF && !seen[$0]++' | head -n 12 > "$RUN_ROOT/meta/selected_ids.txt"

while read -r id; do
  safe_id="$(echo "$id" | tr '/:' '__')"

  if ! papercli info "$id" --provider all --format json --out "$RUN_ROOT/meta/${safe_id}.json"; then
    printf "info\t%s\tmetadata lookup failed\n" "$id" >> "$RUN_ROOT/meta/failures.tsv"
  fi

  if papercli download "$id" --provider all --out "$RUN_ROOT/pdf/${safe_id}.pdf"; then
    printf "%s\n" "$id" >> "$RUN_ROOT/meta/downloaded_ids.txt"
  else
    printf "download\t%s\tpdf download failed\n" "$id" >> "$RUN_ROOT/meta/failures.tsv"
  fi
done < "$RUN_ROOT/meta/selected_ids.txt"

4. Create agent-ready paper summaries

Delegate this step to the paper-summary skill. It centralizes the summary schema, PDF-first evidence rules, and Gemini-based parallel execution.

Run it after $RUN_ROOT/pdf/*.pdf and $RUN_ROOT/meta/*.json are ready:

python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf-dir "$RUN_ROOT/pdf" \
  --metadata-dir "$RUN_ROOT/meta" \
  --summarized-ids "$RUN_ROOT/meta/summarized_ids.txt" \
  --failures-tsv "$RUN_ROOT/meta/failures.tsv" \
  --concurrency 10

Retry one paper with:

python3 SKILLS/paper-summary/scripts/gemini_parallel_summary.py \
  --pdf "$RUN_ROOT/pdf/<safe_id>.pdf" \
  --metadata-dir "$RUN_ROOT/meta" \
  --summarized-ids "$RUN_ROOT/meta/summarized_ids.txt" \
  --failures-tsv "$RUN_ROOT/meta/failures.tsv"

Summary requirements:

• Use the canonical schema in SKILLS/paper-summary/references/summary_schema.md.
• Write each summary to $RUN_ROOT/pdf/<safe_id>.md.
• Treat figures, captions, tables, equations, and layout cues as first-class evidence.
• Mark metadata-only evidence explicitly when the PDF is unreadable.
• Record failures in $RUN_ROOT/meta/failures.tsv so the synthesis step can reconcile counts.

5. Synthesize with explicit comparisons

Build an evidence matrix in the report:

• Rows: papers.
• Columns: task, data, method, metrics, strengths, weaknesses.

Then produce:

• Consensus findings.
• Disputed findings.
• Practical implications for the user's question.
• Base the comparison on the structured summaries in $RUN_ROOT/pdf/, not ad hoc free-form notes.

6. Produce literature-map block diagram

Delegate this step to the shared block-diagram skill. It owns the canonical D2 source, render, validation, and diagram-file delivery flow.

Diagram requirements:

• Base the diagram on the same corpus and [R#] references used in findings.md.
• Show how the strongest papers or paper families connect through evidence-backed relations only.
• Prefer compact family clusters when a flat per-paper graph would be noisy.
• Use a topic-derived slug such as <topic-slug>-literature-map under $RUN_ROOT/diagrams/.
• Prefer png as the primary delivered literature-map artifact.
• Keep svg as the editable or fallback artifact when PNG rendering is unavailable.

Key Math Handling

• Extract at least 3 high-signal equations across the corpus when available.
• Write equations in plain-text markdown, not LaTeX blocks.
• Prefer ASCII-friendly notation that survives raw markdown: use forms like sum_{i=1 to N}, E[...], argmax, <=, >=, and ^.
• Use a consistent three-line pattern:
  • Equation: <name> = <plain-text formula> [R#]
  • Where: <symbol> = <meaning>; ...
  • Interpretation: <role, assumptions, and trade-offs> [R#]
• Explain variable meanings and assumptions.
• Tie each equation to a paper reference on the same line.

Example style:

Equation: L(theta) = sum\_{i=1 to N} ell(f_theta(x_i), y_i) + lambda \* Omega(theta) [R4]
Where: f_theta = model with parameters theta; ell = per-example loss; Omega(theta) = regularizer; lambda = regularization weight.
Interpretation: Regularized empirical risk objective balancing data fit against model complexity [R4].

Output Contract (findings.md)

Use this structure:

# Findings: <research question>

## Research Scope

- Question:
- In/Out of scope:
- Corpus size:
- Corpus stats: selected ..., downloaded ..., summarized ..., failure events ...

## Methodology Snapshot

- Retrieval strategy:
- Selection criteria:
- Reading depth:

## Evidence Matrix

| Ref | Paper | Method | Setting | Best reported result | Limits |
| --- | ----- | ------ | ------- | -------------------- | ------ |
| R1  | ...   | ...    | ...     | ...                  | ...    |

## Core Ideas and Concepts

Paragraph-level synthesis with inline refs [R1][R2].

## Key Math

Equation: <name> = <plain-text formula> [R#]
Where: <symbol> = <meaning>; ...
Interpretation [R3].

## Agreements and Conflicts

- Agreement: ... [R2][R5]
- Conflict: ... [R4][R6]

## Practical Takeaways

- Actionable implication 1 [R1][R7]
- Actionable implication 2 [R3][R8]

## References

| Ref | Title | Authors | Year | Provider ID | Source files                              |
| --- | ----- | ------- | ---- | ----------- | ----------------------------------------- |
| R1  | ...   | ...     | ...  | ...         | `meta/...json`, `pdf/...md`, `pdf/...pdf` |

Companion literature-map artifacts:

• $RUN_ROOT/diagrams/<topic-slug>-literature-map.d2
• $RUN_ROOT/diagrams/<topic-slug>-literature-map.png
• optional $RUN_ROOT/diagrams/<topic-slug>-literature-map.svg

Final Chat Reply

After writing $RUN_ROOT/findings.md, return a short, friendly summary for the user-facing chat reply. Do not alter the findings.md format.

• Keep the reply concise, readable, and confident without sounding casual or sloppy.
• Light emoji use is allowed when it helps the user scan the result quickly.
• Include:
  • one direct-answer line
  • one corpus/method line with selected, downloaded, summarized, and failure counts
  • one short literature-map line explaining how the main papers or paper families connect
  • 3-4 cited takeaways or comparisons
  • one short limitations line when there are real coverage gaps or uncertainty
  • one closing line that points the user to $RUN_ROOT/findings.md for the full analysis
• Do not dump the whole evidence matrix or report body into chat.
• If the active channel supports returning files, return findings.md plus the PNG literature-map diagram after the summary. If PNG rendering is unavailable, return the SVG artifact instead.

Referencing Rules

• Use [R#] inline for claims, numbers, and equation interpretations.
• If a claim cannot be cited, remove or soften it.
• Keep any direct quote short and attributed.

Done Criteria

• findings.md is detailed and decision-useful.
• 8-12 papers were processed (or explain shortfall).
• Math, concepts, and evidence-based synthesis are present.
• Each processed paper has an agent-ready summary in $RUN_ROOT/pdf/ unless extraction failed.
• Selected, downloaded, and summarized counts reconcile with $RUN_ROOT/meta/selected_ids.txt, $RUN_ROOT/meta/downloaded_ids.txt, and $RUN_ROOT/meta/summarized_ids.txt, and failure events reconcile with $RUN_ROOT/meta/failures.tsv.
• References map back to local metadata, colocated paper summaries, and downloaded PDFs.
• A PNG literature-map artifact exists, or an SVG fallback is returned when PNG rendering is unavailable, and the diagram only shows evidence-backed cross-paper connections.
• research/INDEX.md and $RUN_ROOT/RUN.md are updated with final status, corpus counts, artifact paths, and any limitations or next-step notes.