Skip to content

Research ​

Research turns a topic into a browsable, cited website by fanning agents wide across the open web and then narrowing them down: frame the question, scout broadly, rank by credibility, deep-dive the best sources, verify the claims, then synthesize and render a self-contained HTML site. Reach for it when a quick answer is not enough and you want something shareable and sourced that opens offline, whether that is learning a topic, comparing libraries, or mapping an ecosystem. It runs as a budget-aware Workflow, so the heavier presets get clamped down automatically on a tight budget rather than blowing through it.

In Practice ​

Run a default research pass. The mode gets picked from the topic and intent when you do not name one:

/research the state of local-first sync engines

The frame agent infers the intent, chooses a preset (funnel is the sensible default: scout wide, then deep-dive the top-K), and the run fans out from there.

Preview before spending the fan-out. --dry frames the run and stops before any scouting happens:

/research quantum error correction --dry

An example outcome. The brief, the chosen preset, and the resolved B/K/D dials print, and nothing else runs, so you can sanity-check the framing before committing tokens to it.

Map an ecosystem with a diagram. The ecosystem and lineage presets ask the synthesizer for at least one d2 diagram in the bundle:

/research the rust web framework ecosystem --mode ecosystem

Compare candidates instead of writing prose. find-libs and find-similar are compare-shaped intents, so each deep-dive scores the candidate against a rubric instead of extracting claims, and the verify pass is skipped:

/research state management libraries for react --intent find-libs

Re-render a bundle you already have. The workflow returns a bundle, not a file, so a saved one renders straight to html:

nu .claude/skills/research/scripts/render.nu bundle.json --out site.html

Point a wiki at a finished page. The page stays one self-contained file, wiki-link.nu just records and stages it:

nu .claude/skills/research/scripts/wiki-link.nu site.html --wiki ./mywiki --title "State Management Libraries"

An example outcome. The page gets copied into <wiki>/docs/public/research/<slug>.html and an entry lands in <wiki>/research-refs.nuon. The Research sidebar section itself only shows up once a wiki scaffold gen runs with --references <wiki>/research-refs.nuon passed to it, staging alone is not enough.

The Pipeline ​

The workflow's declared phases are Frame, Scout, Rank, Deep, Verify, Synthesize, and Render:

Frame reads a presets config if one exists (a project's .claude/workflows/presets.nuon first, the reference copy second), then one high-effort agent turns the topic into a brief: it sets the intent, picks the preset when the caller left it unset, writes the sub-questions and one search angle per scout, runs a multi-perspective pass for angles the sub-questions would miss, and titles the run. --dry stops here and returns { framed: true, dry: true, brief }.

Scout fans one agent per search angle in parallel, capped at B angles, each returning up to six scored candidate sources. The web-scout agent declares WebSearch and WebFetch in its own tools list, so both stages that use it get the tools already loaded, no prompt has to load them in first. Rank is plain code, not an agent: every candidate is scored relevance x credibility x freshness (credibility comes from a domain-tier table plus small bonuses for being primary, having an author, or having a date), sorted, deduped by normalized url and by same-domain-same-title, and cut to the top K.

Deep fans one agent per top-K source, each reading the full page with WebFetch and following up to D links. On a compare-shaped run it scores the candidate against the rubric columns instead; otherwise it returns a cited section fragment with claims and typed badges (LIB, SEED, CAUTION).

Verify runs an adversarial refute per key claim, but only when the run is not compare-shaped, the preset has D > 0, and the remaining budget is over roughly 80k tokens (VERIFY_FLOOR). It caps how many claims get checked, scaling the cap to the remaining budget (4 to 24 when a budget is set, 16 otherwise), and it flags unsupported claims rather than dropping them.

Synthesize merges the fragments (or the compare rows) into a draft bundle with one high-effort agent, then code builds a deduped bibliography and rewires every claim's cited urls to source indices. The verify pass judged the fragment-level claims, so a token-overlap match (an overlap coefficient, not jaccard, since synth often trims or expands a claim) carries each verdict onto the closest bundle claim, strictly one to one.

Render is where the workflow hands off: the bundle it returns is rendered by the skill's own render.nu, not by the workflow script itself.

Presets and Dials ​

Every preset sets B (scouts fanned wide), K (sources deep-dived), and D (follow-link hops per dive):

presetBKDframing
scout820survey
deep-dive333focused
survey883exhaustive
funnel842ranked
compare552rubric
ecosystem841diagram-led
lineage552time-ordered

A project tunes the numbers in .claude/workflows/presets.nuon, never the preset names, the enum is fixed in the workflow and an unknown name gets ignored. When a budget is set, the dials get clamped down before the fan-out starts: B shrinks to at most room / 30000, K to at most room / 60000, with a floor of 2 scouts and 1 deep-dive, so a survey-scale run can quietly execute at closer to funnel width. The log prints budget clamp when this fires, and --dry shows the resolved numbers before anything else runs.

Key Files ​

The Workflow ​

research.workflow.js ​

The engine – a Workflow-tool script, not a node script. It carries the seven-phase pipeline above, the builtin preset table (the fallback when presets.nuon is missing or broken), the JSON schemas each agent stage returns, the WORKERS map naming which roster agent runs each stage (scout for reading the presets config, web-scout for scouting and deep-diving, web-verifier for verify, synthesizer for synth), and the ranking, dedup, and verdict-carry logic that runs as plain code between agent calls.

Skill and Command ​

skills/research/SKILL.md ​

The routing and procedure doc – how /research parses its arguments, when to warn before a survey-scale run, how to call the Workflow tool (it needs the harness's ultracode opt-in), and how to render and optionally link the result. It points at the bundle-schema reference and the example site rather than documenting the shape itself.

commands/research.md ​

The slash command – the thin /research entry point, parses $ARGUMENTS, follows the skill, and reminds that a real run needs the ultracode opt-in since the engine is a Workflow.

Rendering and Linking ​

skills/research/scripts/render.nu ​

The renderer – turns a bundle JSON into a self-contained single-page site: a vitepress-styled sidebar over panes that switch client-side, badges turned into colored spans, claims that cite into the bibliography, and d2 diagram specs rendered to inline svg through the diagram toolkit (falling back to a plain code block without it). No external http in the output, so the page opens fine over file:///. It finds the diagram toolkit's render.nu relative to itself (two directories up when installed, four up in this repo) unless RESEARCH_DIAGRAM_RENDER names an explicit path, which always wins when set. An example rendered site sits at harness/tests/research/example-site.html.

The wiki linker – records a rendered page in <wiki>/research-refs.nuon (upserted by slug, so re-linking the same page updates in place) and stages a copy into <wiki>/docs/public/research/. It does not render a Research sidebar section itself, that only appears once a wiki scaffold gen runs with --references pointed at the refs file.

Reference ​

skills/research/references/bundle-schema.md ​

The bundle shape – the structured intermediate every stage after synth reads: topic, title, intent, mode, summary, sections (each with claims citing source indices and a verdict), an optional comparison matrix, diagrams, the deduped source bibliography, a glossary, related items, and gaps.

references/presets.nuon ​

The reference preset-to-dial map – the same table above, the copy the module ships and installs as the project's own .claude/workflows/presets.nuon, so a project tunes it by editing this file's installed copy directly.

Connects to ​

  • Fans its agent work onto the scout, web-scout, web-verifier, and synthesizer worker roles named in module.json's needs, each a leaner roster agent than the default one.
  • Diagram rendering (a d2 spec to inline svg) wants the diagram module; without it, or with a spec that fails to compile, that one diagram falls back to a plain code block.
  • wiki-link.nu opt-in stages a page for the wiki module's scaffold gen pass, --references <wiki>/research-refs.nuon, which renders the Research sidebar section.
  • Sibling to deep-research (the fast flat cited answer) and to /wiki (a repo's own code turned into a site): research is neither, it turns the open web into a site.
  • Runs as a Workflow, so a real run (--dry included) needs the harness's ultracode opt-in before anything executes.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/research/USAGE.md – that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module.