fix: keep focused research reports to six passes (#156)

## Summary

- fixes a production QA finding where a concise Research request
silently expanded to ten branches and ran for over twelve minutes
- gives focused deep research a deterministic 3-6-pass contract with a
four-pass default
- reserves larger multi-entity scans for the existing fan-out workflow
- reorders focused passes so concise reports prioritize authoritative
sources, implementation details, and risks

## Production finding

A natural-language Research-mode request for a concise report invoked
`research_deep` with `maxQueries: 10`. The single tool remained in
Working state for more than twelve minutes before being stopped. There
was no retry or disconnect; the excessive branch selection was the
bottleneck.

## Decisions Made

| Decision | Choice | Alternatives considered | Reasoning |
|---|---|---|---|
| Focused depth | 3-6 passes, default 4 | Advisory prompt only; retain
maximum 12 | Enforces predictable latency regardless of model behavior |
| Broad scans | Keep up to 12 in `research_fanout` | Remove broad
coverage | Preserves deliberate exhaustive/multi-entity research |
| Query order | Primary sources, implementation, risks first | Keep
news/competitors first | Produces a useful concise report with only
three passes |

## Verification

- [x] `pnpm lint`
- [x] `pnpm typecheck`
- [x] `pnpm turbo build --force`
- [x] `pnpm deadcode`
- [x] `pnpm architecture:check`
- [x] `pnpm turbo skills:build`
- [ ] production Research run after deployment

Author: iamjr15

packages/agent-core/src/mastra/system-prompt.ts

@@ -232,7 +232,7 @@ Load the generate-media skill before creating or editing an image or generating
 
 const RESEARCH_MODULE = `## Research
 
-Gather sources with search_web / search_web_advanced / search_company / search_web_content, then use search_scrape or search_extract for source retrieval. For an explicit deep-research request, cited report, market analysis, due diligence, broad market scan, or comprehensive investigation, use research_deep; use research_fanout when the request compares many entities or independent angles. Those workflows produce the complete cited PDF deliverable automatically, so do not regenerate it with a document tool. Treat search snippets as leads, not sources — open the real pages and cross-check. Cite as you go: attribute each claim to its source inline with the page title and its URL, and make sure every citation resolves. End a research answer with a short Sources list of the URLs you actually used.`;
+Gather sources with search_web / search_web_advanced / search_company / search_web_content, then use search_scrape or search_extract for source retrieval. For an explicit deep-research request, cited report, market analysis, due diligence, or comprehensive investigation of one topic, use research_deep with 3 queries for a concise/narrow report, 4 by default, and 5-6 only when the user explicitly asks for deeper coverage. Use research_fanout when the request compares many entities or independent angles. Those workflows produce the complete cited PDF deliverable automatically, so do not regenerate it with a document tool. Treat search snippets as leads, not sources — open the real pages and cross-check. Cite as you go: attribute each claim to its source inline with the page title and its URL, and make sure every citation resolves. End a research answer with a short Sources list of the URLs you actually used.`;
 
 /** Compact all-domains pointer for an ambiguous general request — keeps the model aware without the full modules. */
 const GENERALIST_MODULE = `## Choosing your approach

packages/agent-core/src/mastra/tool-defs/research-tools.ts

@@ -248,7 +248,7 @@ export const mastraFirecrawlExtract = createTool({
 export const mastraDeepResearch = createTool({
   id: "research_deep",
   description:
-    "Run the Deep Research workflow for a complex topic. It returns a cited report and saves the complete report as a PDF deliverable in the project.",
+    "Run focused Deep Research for one complex topic and save the cited report as a project PDF. Use 3 queries for concise or narrow reports, 4 by default, and 5-6 only when the user explicitly requests deeper coverage; use research_fanout for broad multi-entity scans.",
   inputSchema: DeepResearchInputSchema,
   outputSchema: ResearchReportArtifactSchema,
   execute: async (input, context) => {

packages/agent-core/src/mastra/workflows/research-schemas.ts

@@ -45,7 +45,15 @@ export const ResearchQuerySchema = z.strictObject({
 });
 
 export const DeepResearchInputSchema = z.strictObject({
-  maxQueries: z.number().int().min(3).max(12).default(6),
+  maxQueries: z
+    .number()
+    .int()
+    .min(3)
+    .max(6)
+    .default(4)
+    .describe(
+      "Focused research pass count: use 3 for a concise or narrow report, 4 by default, and 5-6 only when the user explicitly asks for deeper coverage.",
+    ),
   topic: z.string().trim().min(1).max(2_000),
 });
 

packages/agent-core/src/mastra/workflows/research-support.ts

@@ -4,18 +4,12 @@ export function buildDeepResearchQueries(
 ): Array<{ query: string }> {
   const trimmedTopic = topic.trim();
   const templates = [
-    `${trimmedTopic} current overview and key facts`,
-    `${trimmedTopic} recent developments and news`,
-    `${trimmedTopic} market landscape competitors and alternatives`,
-    `${trimmedTopic} technical details implementation constraints`,
-    `${trimmedTopic} risks limitations criticism`,
-    `${trimmedTopic} primary sources documentation reports`,
-    `${trimmedTopic} case studies adoption examples`,
-    `${trimmedTopic} pricing business model economics`,
-    `${trimmedTopic} legal regulatory policy considerations`,
-    `${trimmedTopic} future roadmap trends forecasts`,
-    `${trimmedTopic} expert analysis long-form review`,
-    `${trimmedTopic} data benchmarks statistics`,
+    `${trimmedTopic} current landscape overview and authoritative primary sources`,
+    `${trimmedTopic} technical product and implementation details constraints`,
+    `${trimmedTopic} risks limitations failure modes criticism`,
+    `${trimmedTopic} evidence data benchmarks case studies adoption`,
+    `${trimmedTopic} legal regulatory economic and operational considerations`,
+    `${trimmedTopic} recent developments future trends disagreements open questions`,
   ];
   return dedupeQueries(templates)
     .slice(0, maxQueries)

skills/deep-research/SKILL.md

@@ -14,7 +14,7 @@ Answer complex questions with sourced synthesis. The output should read like an
 ## Quick Start
 
 1. Scope the user's ask, timeframe, geography, and decision use.
-2. Run the request through `research_deep`; it performs the parallel research, validates citations, and creates the PDF deliverable.
+2. Run the request through `research_deep`; use 3 queries for concise or narrow reports, 4 by default, and 5-6 only when the user explicitly asks for deeper coverage. It validates citations and creates the PDF deliverable.
 3. Return the key conclusion and important caveats in chat, with a short source list.
 4. Refer to the PDF naturally as ready below. Do not call a separate document tool or recreate the report.