run_hypothesis_tournament
Conduct competitive hypothesis tournaments to identify root causes by testing multiple theories in parallel. Uses evidence-based scoring and elimination rounds for efficient issue resolution.
Instructions
Run a competitive hypothesis tournament to find root causes. Multiple AI conversations test different theories in parallel, with evidence-based scoring and elimination rounds.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| claude_context | Yes | ||
| issue | Yes | Description of the issue to investigate | |
| tournament_config | No |
Implementation Reference
- src/index.ts:730-762 (handler)MCP tool dispatch handler for 'run_hypothesis_tournament': parses input using schema, validates context, constructs config, calls DeepCodeReasonerV2.runHypothesisTournament, and formats result as MCP response.
case 'run_hypothesis_tournament': { const parsed = RunHypothesisTournamentSchema.parse(args); // Validate and sanitize the Claude context const validatedContext = InputValidator.validateClaudeContext(parsed.claude_context); // Override with specific values from the parsed input const context: ClaudeCodeContext = { ...validatedContext, analysisBudgetRemaining: 300, // 5 minutes for tournament }; const tournamentConfig = { maxHypotheses: parsed.tournament_config?.max_hypotheses ?? 6, maxRounds: parsed.tournament_config?.max_rounds ?? 3, parallelSessions: parsed.tournament_config?.parallel_sessions ?? 4, }; const result = await deepReasoner.runHypothesisTournament( context, InputValidator.validateString(parsed.issue, 1000), tournamentConfig, ); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } - DeepCodeReasonerV2 handler method: creates or uses HypothesisTournamentService instance and delegates to its runTournament method, with error handling.
async runHypothesisTournament( context: ClaudeCodeContext, issue: string, tournamentConfig?: { maxHypotheses?: number; maxRounds?: number; parallelSessions?: number; }, ): Promise<TournamentResult> { try { // Override tournament config if provided const tournament = tournamentConfig ? new HypothesisTournamentService( this.geminiApiKey, tournamentConfig, ) : this.tournamentService; // Run the tournament const result = await tournament.runTournament(context, issue); return result; } catch (error) { console.error('Hypothesis tournament failed:', { error, issue, tournamentConfig, contextFiles: context.focusArea.files, entryPoints: context.focusArea.entryPoints, }); throw error; } } - Core tournament execution logic: generates hypotheses, runs elimination rounds in parallel, computes winner, extracts findings and recommendations.
async runTournament( context: ClaudeCodeContext, issue: string, ): Promise<TournamentResult> { const startTime = Date.now(); // Generate initial hypotheses const hypotheses = await this.generateHypotheses(context, issue); const rounds: TournamentRound[] = []; let remainingHypotheses = [...hypotheses]; let allFindings: Finding[] = []; // Run tournament rounds for (let roundNum = 1; roundNum <= this.config.maxRounds && remainingHypotheses.length > 1; roundNum++) { const round = await this.runRound( roundNum, remainingHypotheses, context, issue, rounds, ); rounds.push(round); allFindings.push(...this.extractFindingsFromRound(round)); // Eliminate low-confidence hypotheses remainingHypotheses = round.results .filter(r => r.overallConfidence >= this.config.eliminationThreshold) .sort((a, b) => b.overallConfidence - a.overallConfidence) .slice(0, Math.ceil(remainingHypotheses.length / 2)) .map(r => r.hypothesis); // Share insights across sessions if enabled if (this.config.crossPollinationEnabled && remainingHypotheses.length > 1) { await this.crossPollinateInsights(round.results); } } // Determine winner and runner-up const finalResults = rounds[rounds.length - 1]?.results || []; const sortedResults = finalResults.sort((a, b) => b.overallConfidence - a.overallConfidence); const winner = sortedResults[0]; const runnerUp = sortedResults[1]; // Calculate metrics const duration = Date.now() - startTime; const sequentialTime = hypotheses.length * (duration / rounds.length); const parallelEfficiency = sequentialTime / duration; return { issue, totalHypotheses: hypotheses.length, rounds, winner, runnerUp, allFindings, recommendations: this.generateRecommendations(winner, runnerUp, allFindings), duration, parallelEfficiency, }; } - src/index.ts:127-144 (schema)Zod schema for validating run_hypothesis_tournament tool input parameters.
const RunHypothesisTournamentSchema = z.object({ claude_context: z.object({ attempted_approaches: z.array(z.string()), partial_findings: z.array(z.any()), stuck_description: z.string(), code_scope: z.object({ files: z.array(z.string()), entry_points: z.array(z.any()).optional(), service_names: z.array(z.string()).optional(), }), }), issue: z.string(), tournament_config: z.object({ max_hypotheses: z.number().min(2).max(20).optional(), max_rounds: z.number().min(1).max(5).optional(), parallel_sessions: z.number().min(1).max(10).optional(), }).optional(), }); - src/index.ts:418-492 (registration)Tool registration in ListTools response: defines name, description, and inputSchema for MCP tool discovery.
name: 'run_hypothesis_tournament', description: 'Run a competitive hypothesis tournament to find root causes. Multiple AI conversations test different theories in parallel, with evidence-based scoring and elimination rounds.', inputSchema: { type: 'object', properties: { claude_context: { type: 'object', properties: { attempted_approaches: { type: 'array', items: { type: 'string' }, description: 'What Claude Code already tried', }, partial_findings: { type: 'array', description: 'Any findings Claude Code discovered', }, stuck_description: { type: 'string', description: 'Description of where Claude Code got stuck', }, code_scope: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' }, description: 'Files to analyze', }, entry_points: { type: 'array', description: 'Specific functions/methods to start from', }, service_names: { type: 'array', items: { type: 'string' }, description: 'Services involved in cross-system analysis', }, }, required: ['files'], }, }, required: ['attempted_approaches', 'partial_findings', 'stuck_description', 'code_scope'], }, issue: { type: 'string', description: 'Description of the issue to investigate', }, tournament_config: { type: 'object', properties: { max_hypotheses: { type: 'number', minimum: 2, maximum: 20, description: 'Number of initial hypotheses to generate (default: 6)', }, max_rounds: { type: 'number', minimum: 1, maximum: 5, description: 'Maximum tournament rounds (default: 3)', }, parallel_sessions: { type: 'number', minimum: 1, maximum: 10, description: 'Max concurrent conversations (default: 4)', }, }, }, }, required: ['claude_context', 'issue'], }, },