survey

name

survey

description

Synthesize a whole literature into one fixed-template HTML page in the anu atlas (~/.anu/atlas/surveys/<slug>) — the understand-the-FIELD twin of /study (which understands one paper). Assemble a grounded corpus around a topic, seed paper, or a /study dossier's neighborhood, cold-read each paper in parallel, then synthesize a comparison matrix, the schools of thought, consensus vs OPEN disputes, the field arc, and the collective gap. Every paper comes from the `scholar` engine or a source actually fetched — never named from memory; evidence quoted. Its gap[]/disputes[] feed /investigate. Use when the user runs /survey or asks to survey / review the literature / map a field / synthesize the work on / give the lay of the land for a topic.

/survey — literature synthesis

Synthesize a field into one HTML page in the anu atlas — the literature twin of /study. /study understands one paper; /prior-art gives a novelty verdict in chat; /survey synthesizes the whole neighborhood: a grounded corpus, each paper cold-read, then drawn together into a comparison matrix, the schools of thought, what the field agrees on versus the open disputes, the field arc, and the collective gap. One fixed template per run. The page is the artifact — keep the chat output minimal.

Follow the finding-prior-art discipline throughout: never name or characterize a paper from memory. Every record comes from the scholar engine (~/.local/share/anu/plugins/ideas/bin/scholar) or a source actually fetched, and evidence is quoted.

Steps

1. Resolve the input and assemble a GROUNDED corpus (bash + scholar). $ARGUMENTS is a topic/question, OR a seed paper (DOI / arXiv / OpenAlex / URL / title), OR a path to a /study study.json whose neighborhood seeds the corpus.

   SCHOLAR=~/.local/share/anu/plugins/ideas/bin/scholar
   STAMP=$(date '+%Y-%m-%d %H:%M')
   TS=$(date +%Y%m%d-%H%M%S)
   

   • Seed paper: SEED=$("$SCHOLAR" resolve "$ARGUMENTS" --json), then pool scholar similar, scholar cites, and scholar refs on its handle.
   • /study path: read its study.json; seed the pool from its neighbors[].id + lineage.stands_on/led_to ids, set the topic from its paper.title / summary.
   • Topic: scholar search "<formulation>" --json across 3–5 formulations — the topic in the vocabularies different subfields use (one query never covers a field).

   Pool, dedup by DOI / normalized title. Cap the read set to ~16–20 (most-cited + most-recent + closest); say what you capped. Show the corpus (titles + years + count). If it's large or the topic resolved ambiguously, confirm before spending the read fan-out — a survey of the wrong field is worse than none.

2. Run the workflow. Call the Workflow tool with:

   • scriptPath: ~/.local/share/anu/plugins/survey/skills/survey/workflow.js (expand ~ to the real home dir)
   • args: {"topic": "<topic>", "seed": <resolved SEED record or null>, "corpus": [<deduped candidates: {title,id,year}>], "generatedAt": STAMP}

   Wait for it to complete. It returns the survey as a JSON object. (If the corpus is thin, the workflow's Gather phase tops it up via scholar before reading.)

3. Persist and render (bash + Write). Slug from the topic:

   SLUG=$(printf '%s' "<topic>" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//' | cut -c1-60)
   OUT="$HOME/.anu/atlas/surveys/$SLUG"
   mkdir -p "$OUT/history"
   [ -f "$OUT/survey.json" ] && mv "$OUT/survey.json" "$OUT/history/$TS.json"
   

   Write the returned JSON to $OUT/survey.json, then:

   python3 ~/.local/share/anu/plugins/survey/skills/survey/render.py "$OUT/survey.json" "$OUT/index.html"
   open "$OUT/index.html"
   

4. Report: one short paragraph — the page path, the landscape (cluster count, the sharpest open dispute, the collective gap), and the single best opening for /investigate. Do not restate the dossier; the page is where it lives.

Rules

• Never edit template.html or render.py per run. The template is fixed by design; all per-run variation lives in survey.json — same contract as /map and /study.
• A search hit is corpus, not a verdict. The workflow cold-reads each paper (fresh context, fetch + quote) before any synthesis — do not relabel its cards or its disputes from memory.
• Frame the gap and the disputes as bounded by what was searched ("papers do X and Y; none combine Z under W"), never a blanket "unexplored"/"novel".
• The disputes are the gold — surface real tension between papers, with both sides and their ids, not strawmen. They (and the gap) are the seam into /investigate: a survey gap or dispute becomes a falsifiable hypothesis.
• Old runs accumulate in $OUT/history/ — never delete them; they are how a field's neighborhood is diffed over time.
• If scholar returns thin for a formulation, the corpus is smaller and the page says so in coverage — that is honest, not a failure.