ktg-plugin-marketplace/plugins/voyage/commands/trekresearch.md

---
name: trekresearch
description: Deep research combining local codebase analysis with external knowledge, producing structured research briefs with triangulation and confidence ratings
argument-hint: "[--project <dir>] [--quick | --local | --external | --fg] <research question>"
model: opus
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, WebSearch, WebFetch, mcp__tavily__tavily_search, mcp__tavily__tavily_research
---

# Ultraresearch Local v1.0

Deep, multi-phase research that combines local codebase analysis with external
knowledge. Uses specialized agent swarms to investigate multiple dimensions in
parallel, then triangulates findings to produce insights that neither local nor
external research could provide alone.

**Design principle: Context Engineering** — build the right context by orchestrating
specialized agents, each seeing only what they need. The value is in triangulation
(cross-checking local vs. external) and synthesis (insights from combining both).

**Pipeline integration:** Research briefs feed into trekplan via `--research`:
```
/trekresearch <question> → brief → /trekplan --research <brief> <task>
```

## Phase 1 — Parse mode and validate input

Parse `$ARGUMENTS` for mode flags. Flags can appear in any order before the
research question. Collect all flags first, then treat the remainder as the
research question.

Supported flags:

1. `--quick` — lightweight research, no agent swarm. The command itself does
   3-5 targeted searches inline. Set **mode = quick**.

2. `--local` — only codebase research. Skip external agents and gemini bridge.
   Set **scope = local**.

3. `--external` — only external research. Skip codebase analysis agents.
   Set **scope = external**.

4. `--fg` — accepted as a no-op alias for backwards compatibility. Execution
   is always foreground as of v2.4.0. Set **execution = foreground** (the
   only mode).

5. `--project <dir>` — attach this research to an trekbrief project folder.
   The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented
   index) instead of the default `.claude/research/` path. Set **project_dir = {dir}**.

   If `{dir}` does not exist:
   ```
   Error: project directory not found: {dir}
   Run /trekbrief first to create it.
   ```
   Create `{dir}/research/` if it does not already exist.

6. `--gates` — autonomy control. When present, set `gates_mode = true`. The
   research command will pause after each topic completes ("Topic N
   complete. Proceed to topic N+1? (yes/no)"). Default `gates_mode = false`
   means topics run continuously. The flag is consumed by the autonomy-gate
   state machine via the CLI shim:
   `node ${CLAUDE_PLUGIN_ROOT}/lib/util/autonomy-gate.mjs --state X --event Y --gates {true|false}`.

Flags can be combined:
- `--local` — local-only research
- `--external --quick` — external-only, lightweight
- `--project <dir> --external` — attach external research to a project
- `--quick` alone implies both local and external (lightweight)

Defaults: **scope = both**, **execution = foreground** (only mode as of
v2.4.0), **project_dir = none**.

After stripping flags, the remaining text is the **research question**.

If no research question is provided, output usage and stop:

```
Usage: /trekresearch <research question>
       /trekresearch --quick <research question>
       /trekresearch --local <research question>
       /trekresearch --external <research question>
       /trekresearch --fg <research question>
       /trekresearch --project <dir> [--external|--local|--quick|--fg] <research question>

Modes:
  default       Interview → foreground research (local + external) → brief
  --quick       Interview (short) → inline research (no agent swarm)
  --local       Only codebase analysis agents (skip external + Gemini)
  --external    Only external research agents (skip codebase analysis)
  --fg          No-op alias (foreground is the only mode as of v2.4.0)
  --project     Write brief into an trekbrief project folder (auto-indexed)

Flags can be combined: --local, --external --quick, --project <dir> --external

Examples:
  /trekresearch Should we migrate from Express to Fastify?
  /trekresearch --quick What auth libraries are popular for Node.js?
  /trekresearch --local How is error handling structured in this codebase?
  /trekresearch --external What are the security implications of using Redis for sessions?
  /trekresearch --fg --local What patterns does this codebase use for database access?
  /trekresearch --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
```

Do not continue past this step if no question was provided.

Report the detected mode:
```
Mode: {default | quick}, Scope: {both | local | external}, Execution: foreground
Project: {project_dir or "-"}
Question: {research question}
```

### Compute brief destination

If **project_dir is set**:
- Scan `{project_dir}/research/` for existing files matching `NN-*.md`.
- Find the highest existing index; set `N = highest + 1`. If no files exist, `N = 1`.
- Zero-pad to 2 digits: `01`, `02`, ...
- Brief destination: `{project_dir}/research/{NN}-{slug}.md`

If **project_dir is not set**:
- Brief destination: `.claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md`

Store as `brief_destination` for use in later phases.

## Phase 2 — Research interview

Use `AskUserQuestion` to clarify the research question. Ask **one question at a time**.

The interview is shorter than trekplan's (2-4 questions, not 3-8) because research
is more focused than planning.

### Interview flow

**Start with the research question itself.** If the user provided a clear, specific
question, you may skip directly to follow-ups.

**Core questions (pick 2-4 based on clarity of initial question):**

1. **Decision context:** "What decision does this research feed? Are you evaluating
   options, investigating feasibility, or building understanding?"
   *Skip if the question itself makes this obvious.*

2. **Dimensions:** "Are there specific aspects you care about most? (e.g., performance,
   security, migration cost, team learning curve)"
   *Skip if the question is narrow enough that dimensions are obvious.*

3. **Prior knowledge:** "What do you already know about this topic? What have you
   tried or ruled out?"
   *Always useful — prevents redundant research.*

4. **Constraints:** "Are there constraints that should guide the research?
   (e.g., must be open-source, must support X, budget limitations)"
   *Skip if no constraints are apparent.*

**Rules:**
- If the user says "just research it", "skip", or similar — stop interviewing.
  Use the research question as-is.
- For `--quick` mode: ask 1-2 questions maximum.
- Never ask about things you can discover from the codebase.

### Determine research dimensions

Based on the interview, identify 3-8 research dimensions. These are the facets
of the question that will be investigated in parallel. Examples:

- "Should we use Redis?" → dimensions: performance, reliability, operational
  complexity, security, cost, team familiarity
- "How should we handle auth?" → dimensions: standards compliance, implementation
  complexity, library ecosystem, security posture, scalability

Report dimensions:
```
Research dimensions identified:
1. {Dimension 1}
2. {Dimension 2}
...
```

## Phase 3 — Slug and destination (foreground)

Generate a slug from the research question (first 3-4 meaningful words,
lowercase, hyphens). Confirm the `brief_destination` computed in Phase 1.

Report to the user:

```
Research pipeline running in foreground.

  Question: {research question}
  Dimensions: {N} identified
  Scope: {both | local | external}
  Project: {project_dir or "-"}
  Brief:   {brief_destination}
```

Then continue to the next phase inline.

> **Why foreground?** As of v2.4.0 the research-orchestrator is no longer
> spawned as a background agent. The Claude Code harness does not expose the
> Agent tool to sub-agents, so an orchestrator launched with
> `run_in_background: true` cannot spawn the documented research swarm
> (`docs-researcher`, `community-researcher`, etc.) and silently degrades to
> single-context reasoning without WebSearch / Tavily / WebFetch / Gemini.
> Running the phases inline in main context keeps the swarm intact. Use
> `claude -p` in a separate terminal window for long-running headless work.

---

**All remaining phases run inline in the main command context.**

---

## Phase 3.5 — Quick mode (inline research)

**Skip this phase entirely unless mode = quick.**

For quick mode, do NOT launch an agent swarm. Instead, do lightweight research
directly using available tools.

### Quick local research (if scope includes local)

- `Glob` for files matching key terms from the research question (up to 3 patterns)
- `Grep` for relevant definitions, patterns, or usage (up to 5 patterns)
- Read the 2-3 most relevant files found

### Quick external research (if scope includes external)

Use available search tools directly (in this priority order):
1. `mcp__tavily__tavily_search` — if available, use for 2-3 targeted queries
2. `WebSearch` — fallback for 2-3 targeted queries
3. `WebFetch` — fetch 1-2 specific pages if URLs were found

### Quick synthesis

Synthesize findings inline. Write a lightweight research brief to the destination
path, following the research-brief-template but with shorter sections and fewer
dimensions.

Skip to Phase 8 (stats tracking) after writing the brief.

## Phase 4 — Parallel research (agent swarm)

**Determine which agents to launch based on scope:**

### Local agents (scope = both or local)

Reuse existing plugin agents with research-focused prompts. These agents are
designed for planning, but work equally well for research when prompted differently.

| Agent | Purpose in research context |
|-------|----------------------------|
| `architecture-mapper` | How the architecture relates to the research question |
| `dependency-tracer` | Dependencies and integrations relevant to the topic |
| `task-finder` | Existing code that relates to the research question |
| `git-historian` | Recent changes and ownership relevant to the topic |
| `convention-scanner` | Coding patterns relevant to evaluating options |

For each local agent, prompt with the research question, NOT a task description:

- architecture-mapper: "Analyze the architecture relevant to this research question:
  {question}. Focus on how {topic} relates to current patterns and constraints."
- dependency-tracer: "Trace dependencies relevant to this research question: {question}.
  Identify which modules would be affected by {topic}."
- task-finder: "Find existing code relevant to this research question: {question}.
  Look for prior implementations, patterns, or utilities related to {topic}."
- git-historian: "Analyze git history relevant to this research question: {question}.
  Who owns the relevant code? What has changed recently in related areas?"
- convention-scanner: "Discover coding conventions relevant to evaluating {question}.
  What patterns would a solution need to follow?"

### External agents (scope = both or external)

Launch the new research-specialized agents:

| Agent | Purpose |
|-------|---------|
| `docs-researcher` | Official documentation, RFCs, vendor docs |
| `community-researcher` | Real-world experience, issues, blog posts |
| `security-researcher` | CVEs, audit history, supply chain risks |
| `contrarian-researcher` | Counter-evidence, overlooked alternatives |

For each external agent, pass: the research question, specific dimensions to
investigate, and any context from the interview.

### Bridge agent (scope = both or external, if enabled)

Launch `gemini-bridge` with the research question. Do NOT include findings from
other agents — the value of Gemini is independence.

### Launch rules

- Launch ALL selected agents **in parallel** in a single message
- Use model: "sonnet" for all sub-agents (the orchestrator runs on Opus)
- Scale maxTurns by codebase size for local agents (same as trekplan):
  small = halved, medium/large = default
- convention-scanner: medium+ codebases only (50+ files)

## Phase 5 — Targeted follow-ups

Review all agent results. Identify knowledge gaps — areas where findings are
thin, contradictory, or missing.

For each significant gap, launch a targeted follow-up agent (model: "sonnet")
with a narrow, specific brief. Maximum 2 follow-ups.

If no gaps exist, skip: "Initial research sufficient — no follow-ups needed."

## Phase 6 — Triangulation

This is the KEY phase that makes trekresearch more than aggregation.

For each research dimension:

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:
   - External says "library X is fast" → local shows the codebase already uses
     a similar pattern that could benchmark against
   - External says "pattern Y is best practice" → local shows the codebase uses
     pattern Z which conflicts
5. **Rate confidence** per dimension:
   - **high** — multiple authoritative sources agree, local evidence confirms
   - **medium** — good sources but limited cross-validation
   - **low** — single source, limited evidence
   - **contradictory** — credible sources actively disagree

Compute overall confidence as a weighted average (0.0-1.0) based on dimension
confidence levels and their relative importance.

## Phase 7 — Synthesis and brief writing

Read the research brief template:
@${CLAUDE_PLUGIN_ROOT}/templates/research-brief-template.md

Write the research brief following the template. Key rules:

1. **Executive Summary** — 3 sentences. Answer, confidence, key caveat.
2. **Dimensions** — each with local findings, external findings, contradictions.
3. **Synthesis** — NOT a summary. NEW insights from triangulation.
4. **Open Questions** — what remains unresolved and why.
5. **Recommendation** — only if decision-relevant. Omit for exploratory research.
6. **Sources** — every claim traced to URL or codebase path.

Generate the slug from the research question (first 3-4 meaningful words).
Write the brief to the `brief_destination` computed in Phase 1:
- With `--project`: `{project_dir}/research/{NN}-{slug}.md`
- Without `--project`: `.claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md`

Create the parent directory if it does not exist.

## Phase 8 — Present and track

Present a summary to the user:

```
## Ultraresearch Complete

**Question:** {research question}
**Mode:** {default | quick}, Scope: {both | local | external}
**Brief:** {brief_destination}
**Project:** {project_dir or "-"}
**Confidence:** {overall confidence 0.0-1.0}
**Dimensions:** {N} researched
**Agents:** {N} local + {N} external + {gemini: used | unavailable | skipped}

### Key Findings
- {Finding 1}
- {Finding 2}
- {Finding 3}

### Contradictions Found
- {Contradiction 1, or "None — findings are consistent across sources."}

### Open Questions
- {Question 1, or "None — all dimensions adequately covered."}

You can:
- Read the full brief at {brief_destination}
- If `--project` was used: run `/trekplan --project {project_dir}` when all research topics are complete
- Otherwise: `/trekplan --research {brief_destination} --brief <your-brief.md>`
- Ask follow-up questions about specific findings
```

### Stats tracking

Write a session record to `${CLAUDE_PLUGIN_DATA}/trekresearch-stats.jsonl`
(create the file if it does not exist).

Record format (one JSON line):
```json
{
  "ts": "{ISO-8601 timestamp}",
  "question": "{research question (first 100 chars)}",
  "mode": "{default|quick}",
  "scope": "{both|local|external}",
  "slug": "{brief slug}",
  "project_dir": "{project_dir or null}",
  "brief_path": "{brief_destination}",
  "dimensions": {N},
  "agents_local": {N},
  "agents_external": {N},
  "gemini_used": {true|false},
  "confidence": {0.0-1.0},
  "contradictions": {N},
  "open_questions": {N}
}
```

If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.

## Profile (v4.1)

Accepts `--profile <name>` where `<name>` is `economy`, `balanced`, `premium`,
or a custom profile under `voyage-profiles/`. Default: `premium`.

Resolution order (per `lib/profiles/resolver.mjs`):
1. `--profile` flag (source: `flag`)
2. `VOYAGE_PROFILE` env-var (source: `env`)
3. `premium` default (source: `default`)

The profile dictates `phase_models.research`, `parallel_agents`, and
`external_research_enabled`. `economy` and `balanced` profiles auto-disable
the external research swarm regardless of `--external` flag (operator
override deferred to v4.2).

Examples:
```
/trekresearch --profile economy --project .claude/projects/2026-05-09-add-auth
VOYAGE_PROFILE=balanced /trekresearch
```

## Hard rules

- **No planning:** This command produces research briefs, not implementation plans.
  If the user asks to plan, direct them to `/trekplan --research <brief>`.
- **Sources required:** Every claim must cite a source. No unsourced findings.
- **Independence:** Do not pre-bias external agents with local findings or vice versa.
  Triangulate AFTER independent research.
- **Graceful degradation:** If MCP tools are unavailable (Tavily, Gemini, MS Learn),
  proceed with available tools and note limitations in brief metadata.
- **Cost:** Sonnet for all sub-agents. Opus only in the main command/orchestrator.
- **Privacy:** Never log secrets, tokens, or credentials.
- **Honesty:** If the question is trivially answerable, say so. Don't inflate research.
- **Scope of codebase:** Only analyze the current working directory for local research.
- **Research transparency:** Clearly distinguish local findings from external findings.
  Never blend them without attribution.