Deep Research with Sub-agents

Use deep research for evidence, not code search

Choose /deep-research when the answer depends on external facts that may have changed: library behavior, standards, vendor limits, security advisories, academic findings, market evidence, regulations, or architecture options.

Start with a decision-shaped topic

The command accepts the full topic after the slash command. Include the decision, context, constraints, freshness boundary, and required output in that topic.

/deep-research Decide whether Temporal, Restate, Inngest, or a PostgreSQL-backed
queue best fits this TypeScript monorepo as of July 2026. Requirements:
self-hosting, durable execution, at-least-once semantics, human approval steps,
fewer than 50k jobs/day, and a two-person operations team. Read relevant local
architecture files, use primary sources for current capabilities and limits,
compare migration and operating cost, flag uncertain claims, and end with an
ADR-ready recommendation and rejection reasons.

If the topic is too ambiguous to research safely, the workflow asks at most one clarifying question. Otherwise it proceeds and records uncertainty in the report rather than repeatedly interrupting the run.

Understand the research workflow

1. Scope: restate the question and decompose it into four to eight subquestions that together support the decision.
2. Track: use a visible todo list for phases and unanswered subquestions.
3. Discover: search for current sources, then open the strongest pages rather than relying on result snippets.
4. Evaluate: record title, URL, publication date when available, fetched date, source type, and confidence.
5. Cross-check: verify load-bearing facts against two independent sources when possible and surface disagreements or stale claims.
6. Synthesize: answer by theme or subquestion, keep unsupported claims out, and separate facts from inference.
7. Persist: write the complete report and return the exact saved path.

Use sub-agents for independent evidence tracks

The bundled deep-research instructions can use tool discovery when a broad topic benefits from agent, task, or parallel research tools. Make the partition explicit so workers do not repeat the same search.

/deep-research Evaluate passkey adoption for our B2B SaaS authentication
roadmap. If parallel delegation tools are available, use no more than four
read-only research tracks:

1. docs-researcher — current WebAuthn and platform implementation requirements.
2. security-auditor — phishing resistance, recovery, attestation, and threat gaps.
3. competitive-analyst — verified adoption patterns in comparable B2B products.
4. ux-researcher — enrollment, account recovery, device loss, and admin rollout.

Give every track distinct questions and primary-source expectations. The lead
must cross-check claims, resolve contradictions, and write one cited report;
do not concatenate four independent summaries.

Use delegate_parallel for independent, named evidence tracks. Use a persistent team only when every teammate can safely claim every available research task and the run needs dependencies, progress updates, or repeated follow-up. Keep research workers read-only unless one role is explicitly responsible for writing a separate artifact.

Set a source-quality contract

Connect external evidence to the repository

Deep research can read relevant local files. Name them or define the permitted scope so the report translates external facts into project decisions:

Local context to inspect:
- docs/architecture/auth.md
- src/auth/**
- package.json and lockfile versions
- deploy/terraform/**

Do not scan unrelated application data. For every recommendation, identify the
local component affected, the contract that changes, migration prerequisites,
and the verification or rollout evidence we would need.

A local code claim should cite a file and line in the narrative. An external factual claim should use numbered inline citations that resolve to the report's Sources section.

Know the persistence contract

Every run selects an available report path under <project>/.autohand/research/ before research begins:

.autohand/research/topic-durable-workflow-engines.md
.autohand/research/topic-durable-workflow-engines-2.md
.autohand/research/topic-oauth-security-bcp.md

The topic is normalized into a lowercase slug. Existing reports are not overwritten; a numeric suffix is added when the target already exists. The final answer must identify the exact path so later prompts can reuse it.

Required report structure

# Clear decision or research title

## Summary
Decision, strongest evidence, and material caveats.

## Findings
Thematic or subquestion-based analysis with inline citations [1].

## Open questions / uncertainty
Unknowns, contradictions, stale data, and evidence gaps.

## Sources
1. Source title — URL — publication date — fetched date.

Define research completion

A saved file alone is not enough. A complete run should satisfy all of these:

• every scoped subquestion is answered or explicitly marked unresolved;
• load-bearing facts use primary sources and are cross-checked when possible;
• publication and retrieval dates make freshness visible;
• contradictory evidence is resolved or clearly bounded;
• recommendations distinguish evidence, inference, and project-specific judgment;
• the report exists at the selected path and contains inline citations plus a numbered source list.

Command behavior and limitations

• /deep-research requires a topic. Running it without one returns usage guidance.
• The command queues one research workflow. It does not currently expose status, pause, or resume subcommands; the word “status” after the command is treated as part of a topic.
• Web search discovers candidates; the workflow must fetch and read strong sources before citing them.
• Parallel research improves coverage only when tracks are disjoint and the lead performs a real synthesis.
• Research can establish what evidence supports. It cannot replace legal, medical, security, or operational accountability for a final high-stakes decision.

Troubleshooting

The run keeps returning generic summaries

Rewrite the topic around a decision. Add concrete constraints, an as-of date, rejected alternatives, required primary sources, and the exact output format.

Workers repeat the same sources

Partition by subquestion or evidence domain, not by giving every worker the whole topic. Require a unique output contract for each track.

The report has citations but weak evidence

Specify source hierarchy and cross-check rules. A citation proves traceability, not source quality.

The report path is missing

Check .autohand/research/ and session tool failures. The workflow is not complete until it writes the selected file and returns the exact path.