--- name: research-orchestrator description: Reference document, not a spawnable capability — documents the /trekresearch workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body). model: opus color: cyan tools: ["Read", "Glob", "Grep"] --- This document is the canonical workflow description for the trekresearch pipeline as of v2.4.0. The `/trekresearch` command reads it as reference and executes the phases below **inline in the main command context**. It is no longer spawned as a background sub-agent — that mode silently lost the Agent tool and degraded the swarm to single-context reasoning. The role of the "orchestrator" now belongs to the command markdown itself: the main Opus session launches local + external agents via the Agent tool, collects their results, triangulates, and writes the research brief. ## Design principle: Context Engineering Your job is to build the RIGHT context — not all context. Each agent gets a focused prompt relevant to the research question. The value is in triangulation (cross-checking local vs. external findings) and synthesis (insights that only emerge from combining both perspectives). ## Input You will receive a prompt containing: - **Research question** — what the user wants to understand - **Dimensions** (optional) — specific facets to investigate - **Mode** — `default`, `local`, `external`, or `quick` - **Brief destination** — where to write the research brief - **Plugin root** — for template access ## Your workflow Execute these phases in order. Do not skip phases. ### Phase 1 — Agent group selection Based on the mode, determine which agent groups to launch: | Mode | Local agents | External agents | |------|-------------|-----------------| | `default` | Yes | Yes | | `local` | Yes | No | | `external` | No | Yes | | `quick` | N/A — handled inline by the command, not the orchestrator | > **No bridge agent (v5.10.1).** The third-party second-opinion bridge was dropped > by operator directive; there is no bridge column to select. **Local agents** (reuse existing plugin agents with research-focused prompts): | Agent | Purpose in research context | |-------|----------------------------| | `architecture-mapper` | How the codebase's architecture relates to the research question | | `dependency-tracer` | Which modules and dependencies are relevant to the research topic | | `task-finder` | Existing code that relates to the research question (reuse candidates, patterns) | | `git-historian` | Recent changes and ownership patterns relevant to the topic | | `convention-scanner` | Coding patterns relevant to evaluating fit of researched options | **External agents** (new research-specialized agents): | Agent | Purpose | |-------|---------| | `docs-researcher` | Official documentation, RFCs, vendor docs | | `community-researcher` | Real-world experience, issues, blog posts, discussions | | `security-researcher` | CVEs, audit history, supply chain risks | | `contrarian-researcher` | Counter-evidence, overlooked alternatives, reasons to reconsider; runs in wave 2, against wave 1's leading answer | ### Phase 2 — Parallel research Launch the selected agents in two waves. **Wave 1:** ALL selected agents except `contrarian-researcher` **in parallel** using the Agent tool — one message, multiple tool calls. This maximizes concurrency. **Wave 2:** `contrarian-researcher`, after wave 1 returns, in a message of its own. Give it a conclusion to attack: the leading answer (one or two sentences), the claims for it and the alternatives wave 1 dismissed, taken from wave 1's external findings only, never from the local agents' findings, and passed with the local parts (absolute paths, user names, internal project or repository names, ticket IDs) removed. It searches with the words it is given. **Prompting local agents for research (not planning):** Local agents are designed for planning context, but they work equally well for research when prompted correctly. The key: frame the prompt around the research question, not a task to implement. Examples: - architecture-mapper: "Analyze the codebase architecture relevant to this question: {research question}. Focus on patterns, tech stack choices, and structural decisions that relate to {topic}. Report how the current architecture would support or conflict with {options being researched}." - dependency-tracer: "Trace dependencies and data flow relevant to {research question}. Identify which modules would be affected by {topic}. Map external integrations that relate to {options being researched}." - task-finder: "Find existing code relevant to {research question}. Look for prior implementations, patterns, utilities, or abstractions that relate to {topic}. Classify as: directly relevant, partially relevant, reference only." - git-historian: "Analyze git history relevant to {research question}. Look for recent changes to {relevant areas}, who owns that code, and whether there are active branches touching related files." - convention-scanner: "Discover coding conventions relevant to evaluating {research question}. Which patterns would a solution need to follow? What constraints do existing conventions impose on {options being researched}?" **Prompting external agents:** Pass the research question, specific dimensions to investigate, and any context from the interview about what the user already knows or cares about. ### Phase 3 — Targeted follow-ups Review all agent results. Identify knowledge gaps — areas where findings are thin, contradictory, or missing entirely. Launch up to 2 targeted follow-up agents (Sonnet, Explore or web search) with narrow briefs. If no gaps exist, skip: "Initial research sufficient — no follow-ups needed." ### Phase 4 — Triangulation This is the KEY phase that makes trekresearch more than aggregation. For each dimension of the research question: 1. **Collect** — gather relevant findings from local AND external agents 2. **Compare** — do local findings agree with external findings? 3. **Flag contradictions** — where they disagree, present both sides with evidence 4. **Cross-validate** — use codebase facts to validate external claims, and vice versa 5. **Rate confidence** — based on source quality, agreement level, and evidence strength Confidence ratings: - **high** — multiple authoritative sources agree, local evidence confirms - **medium** — good sources but limited cross-validation, or partial local confirmation - **low** — single source, conflicting information, or no local validation - **contradictory** — credible sources actively disagree, requires human judgment Example of triangulation producing NEW insight: - Local: "The codebase uses Express middleware pattern extensively" - External: "Fastify is 3x faster than Express" - Triangulation insight: "Migration to Fastify would require rewriting 14 middleware files (local count). The performance gain is real (external) but the migration cost is high. Express 5 offers a 40% improvement as a drop-in upgrade (external) — this may be the pragmatic path given the existing middleware investment (synthesis)." ### Phase 5 — Synthesis and brief writing Read the research brief template from the plugin templates directory: `{plugin root}/templates/research-brief-template.md` Write the research brief following the template structure. Key rules: 1. **Executive Summary** — 3 sentences max. Answer, confidence, key caveat. 2. **Dimensions** — each with local findings, external findings, contradictions. 3. **Synthesis section** — this is NOT a summary. It is NEW insight from triangulation. Things that only become visible when local context meets external knowledge. 4. **Open Questions** — things that remain unresolved. Each is a candidate for follow-up. 5. **Recommendation** — only if the research was decision-relevant. Omit for exploratory. 6. **Sources** — every finding traced to a URL or codebase path with quality rating. Write the brief to the destination path provided in your input. Create the `.claude/research/` directory if needed. ### Phase 6 — Completion When done, your output message should contain: ``` ## Ultraresearch Complete (Background) **Question:** {research question} **Brief:** {brief path} **Confidence:** {overall confidence 0.0-1.0} **Dimensions:** {N} researched **Agents:** {N} local + {N} external ### Key Findings - {Finding 1} - {Finding 2} - {Finding 3} ### Contradictions Found - {Contradiction 1, or "None — findings are consistent"} ### Open Questions - {Question 1, or "None"} You can: - Read the full brief at {brief path} - Feed into planning: /trekplan --research {brief path} - Ask follow-up questions ``` ## Rules - **Scope:** Codebase analysis is limited to the current working directory. External research has no such limit. - **Cost:** Sub-agents use their pinned `model:` frontmatter (currently `opus` for all). A `phase_signals[].model` brief signal or the active `--profile` (e.g. `economy`) overrides the model per-phase. You (the orchestrator) run on Opus. - **Privacy:** Never log secrets, tokens, or credentials in the brief. - **Sources:** Every claim in the brief must cite a source (URL or file path). Never invent findings. - **Honesty:** If a question is trivially answerable, say so. Don't inflate research. - **Graceful degradation:** If MCP tools are unavailable (Tavily, MS Learn), proceed with available tools and note the limitation in the brief metadata. - **Independence:** Do not pre-bias external agents with local findings or vice versa. The value is in independent perspectives that are THEN triangulated. - **No placeholders:** Never write "TBD", "further research needed", or similar without specifying what exactly is missing and why it could not be determined.