Research Render

Research Render

Wiki pages are the substrate. This skill turns them into multi-form answers — slide decks, charts, canvases, social briefs — and files those outputs back into wiki/renders/<format>/<slug>.{md,png,canvas} so they compound just like any other wiki artifact.

Four formats are supported:

• marp — slide deck (Marp markdown)
• chart — matplotlib chart (PNG + companion .py script for reproducibility)
• canvas — Obsidian Canvas (.canvas JSON)
• brief — social content brief (copy-ready Markdown for a LinkedIn post / Substack note / X thread / Reddit), a reusable idea seed you can paste into a draft

A run can produce several formats at once — the user picks one or many up front (Step 1), and each chosen format is rendered independently.

A fifth notional format ("table") was considered but rejected: tables are best embedded inside comparison wiki pages, which /research already produces via its comparison_writer. If you want a table, ask for a comparison.

Step 1 — Gather inputs and pick the format(s)

You need:

• format(s) — one or more of marp | chart | canvas | brief. Resolve as follows:
  • If the user's verb pins exactly one format unambiguously ("make a slide deck" → marp, "chart this" → chart, "build a canvas" → canvas, "extract a post idea / write a brief" → brief), use it without asking.
  • Otherwise, present a single AskUserQuestion with multiSelect: true offering the four formats, so the user can pick one or render several at once. Capture the result as selected_formats (a list).
• source wiki pages — one or more paths under <research_dir>/wiki/. Most renders draw from a single page; canvases, decks, and briefs often draw from multiple (overview + synthesis + a few entity/concept pages).
• prompt — the user's framing (e.g., "compare BM25 and hybrid retrieval as a 5-slide deck for an internal tech-talk audience"). Verbatim into each render's frontmatter so future agents can reproduce. For a brief, the prompt also carries the body structure the user wants (the sections to cover) — the brief writer follows it for the body (see Format details → Brief).
• platform (brief only, optional) — LinkedIn / Substack note / X thread / Reddit / generic. Infer from the prompt; default to a platform-agnostic brief. Do not interrupt with a separate question — keep the brief lightly platform-aware and leave true platform-final copy to the user.

Locate research_dir the same way /research (query mode) and /research-lint do.

Steps 2–4 run once per selected format. When several formats are chosen, run the idempotency checks per format and spawn the format writers in parallel (Step 4).

Step 2 — Compute the slug + output paths

Slug:

• If the user gave a slug (rare): use it.
• If sources are a single page: derive from that page's slug.
• If sources are multiple: derive from the prompt (≤ 6 words, kebab-case).

Output paths by format:

Create the format directory if it doesn't exist:

mkdir -p "<research_dir>/wiki/renders/<format>"

Step 3 — Idempotency check

Run this check for each selected format (each has its own output path). If the output already exists:

• Read the existing file's frontmatter (for marp / brief, and the .canvas.meta.yaml sidecar for canvas) or companion .py (for chart).
• Compare prompt and sources to the new run.
• If identical, return noop without writing.
• If different, ask the user via AskUserQuestion whether to overwrite, suffix-with-timestamp, or skip.

Step 4 — Spawn the format-specific subagent

Each format has a dedicated subagent that knows its output shape. Pass:

• format
• source_pages — absolute paths
• research_topic, input_summary (from index.yaml)
• prompt
• output_path
• research_dir
• platform — (brief only) the inferred platform, or generic

Each subagent reads its source pages (these are short — entity/concept/comparison/source wiki pages, not raw files), produces the render, and returns a JSON summary on stdout. The orchestrator never reads the source pages itself.

When selected_formats has more than one entry, spawn all the chosen format writers in parallel — one Agent call per format in a single message. They're independent and write to different paths.

For chart only: after the writer subagent saves the .py script, the orchestrator runs it via uv run --script to produce the .png (the script carries a PEP 723 header declaring matplotlib, so it self-bootstraps). The script is the source of truth; the PNG is regenerable. If execution fails, the script stays on disk and the failure is surfaced — the user can fix it and re-run.

For brief only — handle the needs_guidance return. The brief writer is capped at ~1000 words. If covering the prompt's sections faithfully would exceed that, it writes nothing and returns {"action": "needs_guidance", "estimated_words": N, "reason": "...", "options": [...]}. When you get this, do not force the brief — surface it to the user via AskUserQuestion, using the writer's reason as context and its options as the choices (e.g., drop a section, split into two briefs, headline-level only, or raise the cap). Then re-spawn the brief writer with the tightened prompt (or the agreed higher cap). Don't run Steps 5–6 for a brief that returned needs_guidance and wasn't re-rendered.

Step 5 — Update the index

Renders compound. After all selected formats are written, regenerate index.md once so the new renders appear in the navigation:

uv run --script ${CLAUDE_PLUGIN_ROOT:-.claude}/skills/research/scripts/build_index_md.py --research-dir "<research_dir>"

index.yaml does not need to be rebuilt — renders aren't sources, they don't have entries in the sources: array. The total_wiki_pages count is computed live by build_index_md.py from the wiki tree.

Step 6 — Append log entry

One entry per format rendered (share the date when several ran together):

## [YYYY-MM-DD] render | <format> | <slug>

- format: <marp|chart|canvas|brief>
- output: wiki/renders/<format>/<slug>.<ext>
- sources: <count> wiki page(s) — <comma-separated relpaths>
- prompt: "<verbatim prompt, truncated to 200 chars>"

Step 7 — Present results

Tell the user:

• The output path (absolute) and how to view it, for each format rendered
  • marp: open in Obsidian with the Marp plugin, or marp --watch <file> from the CLI
  • chart: open the PNG in any viewer; the companion .py is alongside for editing
  • canvas: open in Obsidian (Canvas is a native plugin)
  • brief: open the .md in Obsidian; copy the body into a post draft, or use it as the idea seed for whatever content workflow you use
• For multi-page renders, the list of source pages used
• The prompt (so they can compare against future renders)

Format details

Marp

Marp is a markdown-based slide format. The output file has a YAML frontmatter block configuring the deck, then --- separators between slides:

---
marp: true
theme: default
paginate: true
backgroundColor: white
sources: [<wiki page paths>]
prompt: "<verbatim>"
created: <ISO-8601>
---

# Title slide

Content

---

## Second slide

- bullet
- bullet

---

...

The Marp Obsidian plugin renders this in-vault. Length: 5–15 slides typical; cap at 25 unless explicitly asked. Each slide ≤ 40 words of body text.