/paper-graph

name: paper-graph
description: "Use this skill to map the **genealogical lineage and historical progression** of a research field. It is designed to visualize the **evolutionary path of ideas**, showing how technical challenges in earlier works were addressed by subsequent research improvements. The final deliverable is a Markdown file with embedded Mermaid diagrams the user can paste into a viewer or commit to their repo. Trigger this when the user needs to understand the **developmental trajectory of a topic**, the 'family tree' of a model, or how a research line matured over multiple years. Do NOT trigger for queries seeking **inventories of specific artifacts**, such as lists of common datasets, benchmarks, or libraries. Avoid this for finding a single 'latest' paper, performing simple keyword search, or conducting head-to-head technical comparisons between specific models. This skill is meant for synthesizing a **chronological narrative of improvement** across multiple works, not for cataloging currently available resources or one-off paper retrieval."
allowed-tools: "write_file edit_file read_file execute"
metadata:
  author: EvoScientist
  version: '0.1.1'
  tags: [research, literature-review, graph, mermaid]

Paper Graph

Build a Markdown report with embedded Mermaid diagrams showing how research on a user-specified topic (or paper) evolved — clustered into challenges → solutions and traced as per-solution evolution paths.

The skill has no outbound LLM dependency. The host agent provides all LLM calls; the skill provides deterministic data fetchers (S2 / DeepXiv), prompt templates, markdown parsers, and Mermaid renderers. Run the runbook below step-by-step.

When to Use This Skill

Trigger when the user asks something like:

• "Show me the history of <topic>" / "How did <topic> evolve?"
• "Where does <paper> stem from?" / "What did <paper> build on?"
• "What are significant improvements / follow-ups to <paper>?"
• "Trace the lineage of ideas in <field>" / "Give me a literature taxonomy of <field>"
• "Citation tree of <paper>" / "Idea trace of <topic>"

Skip when:

• The user just wants a one-paper summary or single search hit (no relational/evolutionary aspect).
• The request is for non-academic citation work.
• The user explicitly wants a plain bibliography rather than a graph.

---

Inputs and Output

**Inputs:**

• A **research query**: a topic, a seed paper title/citation, or a hybrid. Free-form text.
• **Output path** (required): path for the final Markdown report. If not given, ask before running.
• *(Optional)* number of papers to fetch (`--n` flag on `fetch_papers`). Default **10**.
• *(Optional)* Mermaid theme `light` or `dark` (`--theme` on render steps, or `MERMAID_THEME` env). Default **light**.

**Output:** a single Markdown file at the user-specified path with these sections: 1. **Research goal** (extracted from the query) 2. **High-level taxonomy** — one Mermaid graph: root → challenges → solutions → paper references 3. **Per-solution evolution paths** — one Mermaid graph per solution, showing paper-to-paper "evolution from" edges, evolution points, open challenges 4. **Paper appendix** — the numbered list of papers with title / year / authors / abstract / conclusion excerpt

Mermaid is just text inside ```` ```mermaid ```` fences — the file renders directly in GitHub, Obsidian, VS Code with the Mermaid extension, etc.

---

Setup

**Required env (the skill fails verbosely if missing):**

• `S2_API_KEY` — Semantic Scholar API key.

**Optional env:**

• `DEEPXIV_API_TOKEN` (or `DEEPXIV_TOKEN`) — DeepXiv arXiv search fallback. Install with `pip install deepxiv-sdk`; auto-provision with `deepxiv token`. Without it, S2 must fill the cite-number budget on its own.
• `MERMAID_THEME` — `light` (default) or `dark`. Overridden by `--theme` on each render call.

**LLM:** the host agent uses its own model and API key. The skill emits prompt templates and parses responses; it does not authenticate or call any LLM provider.

**Working directory:** create one dir per run, anchored **relative to your current working directory** (e.g. `./<basename>.work/`). Avoid absolute system paths like `/tmp/...` — some harnesses sandbox the shell and the file-read tools to different filesystem roots, so an absolute path can appear writable to one and missing to the other. A cwd-relative path works the same everywhere. Run `pwd` once at the start if unsure.

Suggested layout (assuming final report goes to `<output>`):

<output>.work/
├── query.txt                user query (verbatim)
├── seed.json                resolve_seed_papers
├── seed_block.txt           format_seed_block
├── parsed_query.json        LLM: parse_query output
├── goal_block.txt           build_goal_block (reused in steps 8, 10, 11)
├── papers.json              fetch_papers → prefetch_sections → classify-merged
├── papers_input.txt         format_papers (full set)
├── classify_raw.json        LLM: classify output (consumed by merge_classifications)
├── core_filter.json         compute_core_filter (+ core_filter.json.allowed.txt)
├── papers_input_core.txt    format_papers (CORE-only; + papers_input_core.txt.allowed.txt)
├── outline_raw.md           LLM: outline output
├── outline.json             parse_outline summary
├── outline_mermaid.json     render_outline_mermaid
├── solutions/<key>.json     per-solution context (one file per solution)
├── parsed/<key>.json        parse_detail output (used by step 11 audit)
├── details/
│   ├── <key>_input.txt      format_papers (per-solution allowed set; + .allowed.txt sibling)
│   ├── <key>_raw.md         LLM: detail output
│   └── <key>.json           render_detail_mermaid (consumed by assemble)
├── verdicts/<key>.json      [{source_n, target_n, verdict}] from audit
└── <run>.log.jsonl files    one next to each subcommand output, default-on

Filenames are agent-chosen — these are recommendations to match what the runbook below references. `<key>` is the solut