research

Research Session Orchestrator

Run a full multi-source research session: classify the domain, dispatch parallel agents, synthesize findings, and output a formatted report.

When NOT To Use

Drilling into one subtopic of an active session (use tome:dig)
Merging findings already gathered (use tome:synthesize)

Workflow

Step 1: Classify Domain

Run the domain classifier on the topic:

from tome.scripts.domain_classifier import classify

result = classify(topic)

result.domain, result.triz_depth, result.channel_weights


If confidence < 0.6 the classifier abstains and **refines**
rather than rejecting: `result.candidates` lists the domains
that had keyword support, `triz_depth` becomes the deepest
of those candidates, and `channel_weights` is a
support-weighted blend. Coverage widens on ambiguity instead
of narrowing, because a topic spanning several vocabularies
is exactly what the cross-domain channel is for.

Report the abstention to the user with the candidate list and
let them override the domain. Do not treat a refined plan as
a failure; treat it as the classifier declining to guess.

When `candidates` is empty the topic produced no keyword hits
at all. That stays on the cheap two-channel plan, since there
is nothing to refine toward and escalating noise wastes
budget. If the topic is genuinely researchable, the
vocabulary in `_DOMAIN_KEYWORDS` is missing it: say so rather
than forcing a domain.

### Step 2: Plan Research

```python
from tome.scripts.research_planner import plan

research_plan = plan(result)
# research_plan.channels, research_plan.weights, research_plan.triz_depth

Step 3: Create Session

from tome.session import SessionManager

mgr = SessionManager(Path.cwd())
session = mgr.create(topic, result.domain, result.triz_depth, research_plan.channels)

Step 4: Dispatch Agents

Launch research agents in parallel using the Agent tool. Use this mapping:

Channel	Agent Type	Prompt Includes
code	`tome:code-searcher`	topic
discourse	`tome:discourse-scanner`	topic, domain, subreddits
academic	`tome:literature-reviewer`	topic, domain
web	`tome:web-searcher`	topic, domain
triz	`tome:triz-analyst`	topic, domain, triz_depth

Rules:

Dispatch every channel in research_plan.channels, which the planner derives from each card's min_depth: code and discourse at every depth, academic and web from medium, triz from deep
Dispatch all eligible agents in a SINGLE message (parallel, not sequential)

Each agent prompt must include:

The topic string
The domain classification
Any channel-specific context (subreddits for discourse, triz_depth for triz)
The channel's card, from render_card(get_card(channel)) in tome.channels.cards. It carries the channel's limitations and points the agent at the envelope its own file documents. Do not dictate a return shape in the prompt: an agent obeys the prompt over its file, and a prompt-invented shape once cost a session its canary record.

The rows above restate the cards. The cards are what the planner gates on, and a drift test holds the two together.

Step 5: Collect and Synthesize

After all agents return:

Parse each agent's findings into Finding objects
Record what each agent actually searched, before merging anything:
```
from tome.synthesis.quality import parse_envelope

for envelope in agent_envelopes:  # one per dispatched agent
    session.query_log.extend(parse_envelope(envelope))
```
This is the step that makes an empty channel readable. Findings record what was found; the query log records what was looked for, and without it a channel that errored and a channel that searched a thin topic are the same thing: no findings. Skip this and every channel in the report reads unknown.
Merge using tome.synthesis.merger.merge_findings()
Rank using tome.synthesis.ranker.rank_findings()

Step 5b: Verify, Then Loop or Stop

from tome.synthesis.verifier import verify_context

check = verify_context(session, passes_run=n)  # max_passes default 2

CONTINUE names the work and why:

rerun: the channel failed, degraded, left no record, or cannot show it was able to search. Dispatch it again as is.
reformulate: a venue mismatch. Dispatch it again with the vocabulary the productive channel's findings use.
add: a thin-field candidate that a retrieval channel never looked at. Dispatch that channel.

Dispatch only those agents, append their envelopes to the same session, merge and rank again, then verify with passes_run raised by one. STOP goes to Step 6. A STOP on the pass budget (max_passes, default 2) still lists the undone work: report it as a gap, never as a finished search. Each check's detail says what it read. See modules/stop-verifier.md for why the decision comes from records and not from a judgment.

Step 6: Generate Output

from tome.output.report import format_report, format_brief, format_transcript

# Default to report format
output = format_report(session)

# Save to docs/research/
output_path = f"docs/research/{session.id}-{slug}.md"

Save the session state:

mgr.save(session)

Step 7: Present Results

Display a brief summary to the user:

The frontier verdict and its reason, from tome.synthesis.frontier.frontier_verdict(session). It is the report's own answer to "did we find little because there is little, or because the search went badly"
Number of findings per channel, with its outcome status from tome.synthesis.quality.channel_outcomes(session): ok, empty, error, rate_limited, degraded, or unknown
Top 3 findings by relevance
Path to saved report
Any research stories from tome.synthesis.frontier.frontier_stories(session). Each is a gap with its evidence, and each arrives undecided. Ask the user to mark it act, defer, or decline. Do not decide for them, and do not file an issue for a story they have not marked: nothing in a search record says what is worth this project's time. On defer, file it with minister:create-issue so it survives the session. On act the work starts now and needs no issue. On decline record nothing.

The three retrieval channels run a positive control before their topic queries, so INCONCLUSIVE now means something specific rather than "controls do not exist yet". Read it as one of two things: a channel failed its canary and is blind, or a channel searched without running one. Both are named in the verdict's evidence, and both produce a story under Research Stories.

triz runs no control and is excluded from the verdict. It generates analogies rather than retrieving prior work, so its output is not evidence about what has been published and its findings are not counted toward coverage.

State plainly which channels did not return cleanly. A summary that reports "3 findings" without saying two channels were rate-limited invites the reader to treat a half-run search as a finding about the topic.

Then offer interactive refinement: "Use /tome:dig \"subtopic\" to explore specific areas."

Error Handling

If an agent fails, continue with remaining agents
If all agents fail, report the error and suggest manual research approaches
If synthesis produces 0 findings, state this clearly rather than generating an empty report
Save session state even on partial failure

Output Format Selection

Flag	Format	Function
(default)	report	`format_report()`
`--format brief`	brief	`format_brief()`
`--format transcript`	transcript	`format_transcript()`

Exit Criteria

Domain classified before agents are dispatched; if confidence < 0.6, user confirmation is requested before proceeding
Every channel in research_plan.channels was dispatched, none outside it, all in a single parallel message
Every dispatch prompt embeds render_card output for its channel and dictates no return shape of its own
verify_context ran after every pass; the report was written only after it returned STOP, and no more than max_passes passes ran
A budget STOP with rerun, reformulate, or add left non-empty names those channels as gaps in the summary
Session saved to docs/research/{session.id}-{slug}.md after synthesis regardless of whether all agents succeeded
Top 3 findings by relevance score displayed to the user with the path to the saved report
If all agents fail, error reported and manual alternatives suggested; an empty report is never generated