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, ask the user to confirm or override

the domain classification before proceeding.

Step 2: Plan Research

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 |

| triz | tome:triz-analyst | topic, domain, triz_depth |

Rules:

• Always dispatch code and discourse agents
• Dispatch academic agent only if "academic" is in

research_plan.channels

• Dispatch triz agent only if "triz" is in

research_plan.channels AND triz_depth != "light"

• 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)

• Instruction to return findings as JSON

Step 5: Collect and Synthesize

After all agents return:

• Parse each agent's findings into Finding objects
• Merge using tome.synthesis.merger.merge_findings()
• Rank using tome.synthesis.ranker.rank_findings()

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:

• Number of findings per channel
• Top 3 findings by relevance
• Path to saved report

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

• [ ] Code and discourse agents always dispatched; academic and triz

agents dispatched only when their channels are in the plan;

all eligible agents sent in a single parallel message

• [ ] 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