How the Wigolo Research Tool Decomposes Complex Questions into Sub‑Queries

Wigolo breaks complex research questions into targeted sub‑queries using a hybrid strategy that combines LLM‑based sampling, rule‑driven templates, and linguistic heuristics to ensure comprehensive search coverage regardless of available compute.

The KnockOutEZ/wigolo repository implements a sophisticated research pipeline that transforms broad user questions into actionable search queries. At the heart of this system lies a multi‑layered decomposition engine located in src/research/decompose.ts, which orchestrates the transition from natural language input to parallelized sub‑query execution. Understanding this decomposition mechanism reveals how Wigolo maintains research thoroughness while adapting to environments with or without host LLM access.

Core Decomposition Pipeline in Wigolo

Wigolo’s decomposition process follows a cascading decision tree that prioritizes intelligent sampling when available, but remains robust through deterministic fallbacks. The decomposeQuestion function exported from src/research/decompose.ts implements this logic through four distinct phases.

Query Type Detection

Before generating sub‑queries, Wigolo classifies the input using detectQueryType (lines 45‑71 in src/research/decompose.ts). This function inspects lexical patterns to categorize questions as comparison, how‑to, concept, or general queries. The classification determines which template set applies during later stages and influences how the final research brief gets structured in src/research/brief.ts.

Sampling‑Based Decomposition

When a SamplingCapableServer is configured, Wigolo attempts LLM‑driven decomposition first. The system sends a constrained prompt requesting exactly N sub‑queries, where N corresponds to the research depth (2 for quick, 4 for standard, 7 for comprehensive). If the LLM returns valid JSON containing a string array (lines 69‑88), Wigolo uses these queries directly and sets the samplingUsed flag to true, bypassing template logic entirely.

Template‑Driven Decomposition

If sampling is unavailable or fails validation, Wigolo falls back to deterministic templates based on the detected query type:

• Comparison queries: The system invokes extractComparisonEntities to identify compared items, then generates per‑entity investigations, cross‑comparisons, and ecosystem‑level queries (lines 40‑62).
• How‑to and concept queries: The algorithm produces variant queries targeting tutorials, best practices, common pitfalls, and overview content derived from the cleaned input string (lines 63‑99).

These templates ensure that even without LLM access, Wigolo produces semantically relevant search variations.

Heuristic Fallback Mechanisms

When templates fail to yield sufficient queries, Wigolo employs linguistic heuristics to reach the target count (lines 102‑141 in src/research/decompose.ts). The system splits sentences at clause boundaries, extracts noun phrases using pattern matching, generates keyword‑variant fragments, and pads the result set with generic "aspect N" placeholders. This guarantees that the pipeline always receives the exact number of sub‑queries required for the requested depth level.

Deduplication and Ordering

Final processing occurs in src/research/pipeline.ts (lines 71‑92), where the subQueries array undergoes case‑insensitive deduplication. Crucially, the original full question is prepended to the array if not already present, ensuring that the exact user phrasing always participates in the search fan‑out alongside the derived sub‑queries.

Integration with the Research Pipeline

The runResearchPipeline function in src/research/pipeline.ts invokes decomposeQuestion during Phase 1 of execution. The depth parameter—quick, standard, or comprehensive—controls the cardinality of the sub‑query set (lines 32‑36). These sub‑queries then drive parallel searches across configured engines, with results aggregated and synthesized into the final report via src/tools/research.ts.

Practical Implementation Example

Below is a TypeScript implementation demonstrating manual invocation of the decomposition engine:

// Example: manually decompose a question
import { decomposeQuestion } from './src/research/decompose.ts';

// Simulate a server that supports sampling (or pass undefined to skip sampling)
const server = undefined; // replace with a SamplingCapableServer if you have one

async function demo() {
  const question = "How does the wigolo research tool decompose complex questions into sub‑queries?";
  const { subQueries, samplingUsed, queryType } = await decomposeQuestion(
    question,
    'standard',   // depth = quick | standard | comprehensive
    server,
  );

  console.log('Query type:', queryType);
  console.log('Sampling used?', samplingUsed);
  console.log('Generated sub‑queries:');
  subQueries.forEach((q, i) => console.log(`${i + 1}. ${q}`));
}

demo();

Typical output without sampling:

Query type: how-to
Sampling used? false
Generated sub‑queries:
1. How does the wigolo research tool decompose complex questions into sub‑queries?
2. How does the wigolo research tool decompose complex questions tutorial guide
3. How does the wigolo research tool decompose complex questions best practices
4. How does the wigolo research tool decompose complex questions common mistakes pitfalls

When a sampling‑enabled server is provided, the LLM may return a divergent set of concise queries, with samplingUsed reflecting true.

Summary

• Multi‑modal decomposition: Wigolo prioritizes LLM sampling, falls back to type‑specific templates, and ultimately uses linguistic heuristics to guarantee sub‑query generation.
• Query classification: The detectQueryType function categorizes inputs into comparison, how‑to, concept, or general types to guide template selection.
• Depth control: Research intensity determines sub‑query count—2 for quick, 4 for standard, and 7 for comprehensive modes.
• Pipeline integration: src/research/pipeline.ts deduplicates results and prepends the original question before executing parallel searches.
• Implementation location: Core logic resides in src/research/decompose.ts, orchestrated by runResearchPipeline in src/research/pipeline.ts.

Frequently Asked Questions

What file contains the main decomposition logic in Wigolo?

The primary decomposition implementation lives in src/research/decompose.ts. This file exports decomposeQuestion, detectQueryType, and extractComparisonEntities, which together handle query classification, LLM sampling, template generation, and heuristic fallback strategies.

How does Wigolo decide between LLM sampling and template decomposition?

Wigolo attempts sampling first when a SamplingCapableServer instance is provided. If the LLM returns valid JSON within the expected schema, the system uses those results immediately. If the server is undefined, returns malformed data, or throws an exception, Wigolo automatically falls back to the deterministic template system based on the detected query type.

What happens if template generation produces too few sub‑queries?

The system enters a heuristic fallback phase defined in lines 102‑141 of src/research/decompose.ts. It deconstructs the original question into clauses and noun phrases, generates keyword variants, and appends generic "aspect N" placeholders until reaching the target count specified by the research depth parameter.

Can I customize the number of sub‑queries Wigolo generates?

The sub‑query count is controlled through the depth parameter passed to decomposeQuestion. Valid values are quick (2 queries), standard (4 queries), and comprehensive (7 queries). These constants are enforced in src/research/pipeline.ts (lines 32‑36) and propagated through the decomposition chain.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}