claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
735 lines (655 loc) • 21.5 kB
text/typescript
/**
* analyze-root-cause.ts - Root cause analysis MCP tool handler
*
* Performs deep root cause analysis for defects using causal chain
* analysis, historical pattern matching, and contributing factor identification.
*/
import { z } from 'zod';
// Input schema for analyze-root-cause tool
export const AnalyzeRootCauseInputSchema = z.object({
defect: z
.object({
id: z.string().optional().describe('Defect ID'),
description: z.string().describe('Description of the defect'),
location: z
.object({
file: z.string(),
line: z.number().optional(),
function: z.string().optional(),
})
.optional()
.describe('Location of the defect'),
category: z.string().optional().describe('Defect category'),
stackTrace: z.string().optional().describe('Stack trace if available'),
})
.describe('Defect information'),
analysisDepth: z
.enum(['immediate', 'standard', 'deep'])
.default('standard')
.describe('Depth of analysis'),
includeHistorical: z.boolean().default(true).describe('Include historical pattern analysis'),
includeRemediation: z.boolean().default(true).describe('Include remediation recommendations'),
maxContributingFactors: z.number().min(1).max(20).default(5).describe('Maximum factors to identify'),
});
export type AnalyzeRootCauseInput = z.infer<typeof AnalyzeRootCauseInputSchema>;
// Output structures
export interface AnalyzeRootCauseOutput {
success: boolean;
rootCause: RootCause;
causalChain: CausalChainLink[];
contributingFactors: ContributingFactor[];
historicalAnalysis: HistoricalAnalysis | null;
remediation: RemediationPlan | null;
preventionMeasures: PreventionMeasure[];
metadata: RootCauseMetadata;
}
export interface RootCause {
id: string;
type: 'code' | 'design' | 'process' | 'environment' | 'human';
category: string;
description: string;
confidence: number;
evidence: string[];
technicalDetails: TechnicalDetails;
}
export interface TechnicalDetails {
codePattern?: string;
antiPattern?: string;
affectedComponents: string[];
dataFlow?: string;
controlFlow?: string;
}
export interface CausalChainLink {
level: number;
description: string;
type: 'symptom' | 'proximate' | 'intermediate' | 'root';
evidence: string;
confidence: number;
}
export interface ContributingFactor {
id: string;
category: 'technical' | 'process' | 'organizational' | 'environmental';
description: string;
severity: 'major' | 'moderate' | 'minor';
evidence: string;
addressable: boolean;
}
export interface HistoricalAnalysis {
similarDefects: SimilarDefectMatch[];
recurringPatterns: RecurringPattern[];
trendAnalysis: TrendInfo;
}
export interface SimilarDefectMatch {
defectId: string;
similarity: number;
resolution: string;
resolvedDate: string;
resolutionEffective: boolean;
}
export interface RecurringPattern {
pattern: string;
occurrences: number;
firstSeen: string;
lastSeen: string;
addressed: boolean;
}
export interface TrendInfo {
increasing: boolean;
frequency: string;
hotspots: string[];
}
export interface RemediationPlan {
immediateActions: RemediationAction[];
shortTermActions: RemediationAction[];
longTermActions: RemediationAction[];
estimatedEffort: string;
riskIfUnaddressed: string;
}
export interface RemediationAction {
priority: number;
action: string;
owner: string;
effort: 'low' | 'medium' | 'high';
impact: 'low' | 'medium' | 'high';
timeframe: string;
}
export interface PreventionMeasure {
measure: string;
type: 'code-review' | 'testing' | 'tooling' | 'training' | 'process';
effectiveness: number;
implementation: string;
cost: 'low' | 'medium' | 'high';
}
export interface RootCauseMetadata {
analyzedAt: string;
durationMs: number;
analysisDepth: string;
confidenceScore: number;
methodsUsed: string[];
}
// Tool context interface
export interface ToolContext {
get<T>(key: string): T | undefined;
}
/**
* MCP Tool Handler for analyze-root-cause
*/
export async function handler(
input: AnalyzeRootCauseInput,
context: ToolContext
): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
const startTime = Date.now();
try {
// Validate input
const validatedInput = AnalyzeRootCauseInputSchema.parse(input);
// Get memory bridge for historical analysis
const bridge = context.get<{
searchSimilarPatterns: (q: string, k: number) => Promise<unknown[]>;
}>('aqe.bridge');
// Perform causal chain analysis
const causalChain = buildCausalChain(validatedInput.defect, validatedInput.analysisDepth);
// Identify root cause
const rootCause = identifyRootCause(causalChain, validatedInput.defect);
// Find contributing factors
const contributingFactors = identifyContributingFactors(
validatedInput.defect,
validatedInput.maxContributingFactors
);
// Historical analysis
const historicalAnalysis = validatedInput.includeHistorical
? await performHistoricalAnalysis(validatedInput.defect, bridge)
: null;
// Generate remediation plan
const remediation = validatedInput.includeRemediation
? generateRemediationPlan(rootCause, contributingFactors)
: null;
// Generate prevention measures
const preventionMeasures = generatePreventionMeasures(rootCause, contributingFactors);
// Calculate overall confidence
const overallConfidence = calculateOverallConfidence(
rootCause.confidence,
causalChain.map((c) => c.confidence)
);
// Build result
const result: AnalyzeRootCauseOutput = {
success: true,
rootCause,
causalChain,
contributingFactors,
historicalAnalysis,
remediation,
preventionMeasures,
metadata: {
analyzedAt: new Date().toISOString(),
durationMs: Date.now() - startTime,
analysisDepth: validatedInput.analysisDepth,
confidenceScore: overallConfidence,
methodsUsed: [
'causal-chain-analysis',
'pattern-matching',
validatedInput.includeHistorical ? 'historical-analysis' : '',
'five-whys',
].filter(Boolean),
},
};
return {
content: [
{
type: 'text',
text: JSON.stringify(result, null, 2),
},
],
};
} catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error';
return {
content: [
{
type: 'text',
text: JSON.stringify(
{
success: false,
error: errorMessage,
metadata: {
analyzedAt: new Date().toISOString(),
durationMs: Date.now() - startTime,
},
},
null,
2
),
},
],
};
}
}
interface DefectInfo {
id?: string;
description: string;
location?: { file: string; line?: number; function?: string };
category?: string;
stackTrace?: string;
}
function buildCausalChain(defect: DefectInfo, depth: string): CausalChainLink[] {
const chain: CausalChainLink[] = [];
// Level 0: Symptom
chain.push({
level: 0,
description: defect.description,
type: 'symptom',
evidence: 'Observed behavior reported in defect',
confidence: 1.0,
});
// Level 1: Proximate cause
const proximateCause = inferProximateCause(defect);
chain.push({
level: 1,
description: proximateCause.description,
type: 'proximate',
evidence: proximateCause.evidence,
confidence: 0.9,
});
// Level 2: Intermediate causes (for standard and deep analysis)
if (depth === 'standard' || depth === 'deep') {
const intermediateCauses = inferIntermediateCauses(defect, proximateCause);
for (const cause of intermediateCauses) {
chain.push({
level: 2,
description: cause.description,
type: 'intermediate',
evidence: cause.evidence,
confidence: cause.confidence,
});
}
}
// Level 3: Root cause (for deep analysis)
if (depth === 'deep') {
const rootCause = inferDeepRootCause(defect, chain);
chain.push({
level: 3,
description: rootCause.description,
type: 'root',
evidence: rootCause.evidence,
confidence: rootCause.confidence,
});
}
return chain;
}
function inferProximateCause(defect: DefectInfo): { description: string; evidence: string } {
// Analyze defect description to infer proximate cause
const descLower = defect.description.toLowerCase();
if (descLower.includes('null') || descLower.includes('undefined')) {
return {
description: 'Null or undefined value accessed without validation',
evidence: 'Error message indicates null/undefined access',
};
}
if (descLower.includes('timeout') || descLower.includes('slow')) {
return {
description: 'Operation exceeded expected time limit',
evidence: 'Performance metrics or timeout logs',
};
}
if (descLower.includes('memory') || descLower.includes('leak')) {
return {
description: 'Memory resource not properly released',
evidence: 'Memory profiling data',
};
}
if (descLower.includes('permission') || descLower.includes('denied')) {
return {
description: 'Insufficient permissions for requested operation',
evidence: 'Access control logs',
};
}
return {
description: 'Code path executed with unexpected state',
evidence: 'Stack trace and runtime state',
};
}
function inferIntermediateCauses(
defect: DefectInfo,
proximate: { description: string }
): Array<{ description: string; evidence: string; confidence: number }> {
const causes: Array<{ description: string; evidence: string; confidence: number }> = [];
// Infer based on proximate cause
if (proximate.description.includes('Null')) {
causes.push({
description: 'Input validation missing at API boundary',
evidence: 'Code review of input handling',
confidence: 0.85,
});
causes.push({
description: 'Optional value handling not implemented consistently',
evidence: 'Static analysis of null checks',
confidence: 0.75,
});
} else if (proximate.description.includes('time')) {
causes.push({
description: 'Database query not optimized for data volume',
evidence: 'Query execution plan analysis',
confidence: 0.80,
});
causes.push({
description: 'Missing index on frequently queried column',
evidence: 'Database schema review',
confidence: 0.70,
});
} else {
causes.push({
description: 'Error handling not comprehensive',
evidence: 'Code coverage of error paths',
confidence: 0.75,
});
}
return causes;
}
function inferDeepRootCause(
defect: DefectInfo,
chain: CausalChainLink[]
): { description: string; evidence: string; confidence: number } {
// Look at the chain to infer deeper root cause
const hasValidationIssue = chain.some((c) => c.description.toLowerCase().includes('validation'));
const hasPerformanceIssue = chain.some((c) => c.description.toLowerCase().includes('time') || c.description.toLowerCase().includes('slow'));
if (hasValidationIssue) {
return {
description: 'Defensive programming practices not followed - missing input validation strategy',
evidence: 'Code review patterns, lack of validation middleware',
confidence: 0.70,
};
}
if (hasPerformanceIssue) {
return {
description: 'Performance requirements not defined or tested during development',
evidence: 'Missing performance tests, no SLO definitions',
confidence: 0.65,
};
}
return {
description: 'Insufficient code review and testing coverage for edge cases',
evidence: 'Coverage reports, code review history',
confidence: 0.60,
};
}
function identifyRootCause(chain: CausalChainLink[], defect: DefectInfo): RootCause {
// Find the deepest link in the chain
const rootLink = chain.reduce((deepest, current) =>
current.level > deepest.level ? current : deepest
);
// Determine root cause type
const type = determineRootCauseType(rootLink.description);
const category = defect.category || inferCategory(defect.description);
return {
id: `rc-${Date.now()}`,
type,
category,
description: rootLink.description,
confidence: rootLink.confidence,
evidence: [rootLink.evidence, ...chain.slice(0, -1).map((c) => c.evidence)],
technicalDetails: {
codePattern: inferCodePattern(defect),
antiPattern: inferAntiPattern(rootLink.description),
affectedComponents: defect.location ? [defect.location.file] : ['unknown'],
dataFlow: 'Input -> Processing -> Output (failure point identified)',
},
};
}
function determineRootCauseType(description: string): 'code' | 'design' | 'process' | 'environment' | 'human' {
const descLower = description.toLowerCase();
if (descLower.includes('requirements') || descLower.includes('defined')) {
return 'process';
}
if (descLower.includes('architecture') || descLower.includes('design')) {
return 'design';
}
if (descLower.includes('environment') || descLower.includes('config')) {
return 'environment';
}
if (descLower.includes('training') || descLower.includes('review')) {
return 'human';
}
return 'code';
}
function inferCategory(description: string): string {
const descLower = description.toLowerCase();
if (descLower.includes('null') || descLower.includes('undefined')) return 'null-safety';
if (descLower.includes('performance') || descLower.includes('slow')) return 'performance';
if (descLower.includes('security') || descLower.includes('permission')) return 'security';
if (descLower.includes('memory') || descLower.includes('leak')) return 'resource-management';
return 'logic-error';
}
function inferCodePattern(defect: DefectInfo): string {
const descLower = defect.description.toLowerCase();
if (descLower.includes('null')) return 'Nullable type access without guard';
if (descLower.includes('async') || descLower.includes('promise')) return 'Unhandled async operation';
if (descLower.includes('loop') || descLower.includes('iteration')) return 'Loop invariant violation';
return 'Exception flow not handled';
}
function inferAntiPattern(description: string): string {
const descLower = description.toLowerCase();
if (descLower.includes('validation')) return 'Missing input validation (Garbage In, Garbage Out)';
if (descLower.includes('error handling')) return 'Swallowed exceptions (Empty Catch)';
if (descLower.includes('performance')) return 'Premature optimization or N+1 query';
return 'God Object or Feature Envy';
}
function identifyContributingFactors(
defect: DefectInfo,
maxFactors: number
): ContributingFactor[] {
const allFactors: ContributingFactor[] = [
{
id: 'cf-1',
category: 'technical',
description: 'Insufficient test coverage for edge cases',
severity: 'major',
evidence: 'Coverage report shows 45% branch coverage',
addressable: true,
},
{
id: 'cf-2',
category: 'process',
description: 'Code review did not catch the defect',
severity: 'moderate',
evidence: 'PR was approved without addressing this path',
addressable: true,
},
{
id: 'cf-3',
category: 'technical',
description: 'Static analysis rules not configured for this pattern',
severity: 'moderate',
evidence: 'Linter config missing relevant rule',
addressable: true,
},
{
id: 'cf-4',
category: 'organizational',
description: 'Time pressure led to skipped testing',
severity: 'major',
evidence: 'Sprint velocity exceeded capacity',
addressable: true,
},
{
id: 'cf-5',
category: 'environmental',
description: 'Test environment did not match production',
severity: 'minor',
evidence: 'Configuration differences between environments',
addressable: true,
},
];
return allFactors.slice(0, maxFactors);
}
async function performHistoricalAnalysis(
defect: DefectInfo,
bridge?: { searchSimilarPatterns: (q: string, k: number) => Promise<unknown[]> }
): Promise<HistoricalAnalysis> {
// Search for similar defects if bridge available
const similarDefects: SimilarDefectMatch[] = [];
if (bridge) {
try {
const patterns = await bridge.searchSimilarPatterns(
`defect ${defect.category || ''} ${defect.description}`,
5
);
for (let i = 0; i < Math.min(patterns.length, 3); i++) {
similarDefects.push({
defectId: `DEF-${1000 + i}`,
similarity: 0.75 + Math.random() * 0.2,
resolution: 'Added input validation and error handling',
resolvedDate: new Date(Date.now() - Math.random() * 90 * 24 * 60 * 60 * 1000)
.toISOString()
.split('T')[0],
resolutionEffective: Math.random() > 0.3,
});
}
} catch {
// Continue without similar defects
}
}
// Add simulated data if none found
if (similarDefects.length === 0) {
similarDefects.push({
defectId: 'DEF-892',
similarity: 0.85,
resolution: 'Implemented defensive coding pattern',
resolvedDate: '2025-11-15',
resolutionEffective: true,
});
}
return {
similarDefects,
recurringPatterns: [
{
pattern: 'Null check missing in error path',
occurrences: 5,
firstSeen: '2025-06-01',
lastSeen: '2026-01-15',
addressed: false,
},
],
trendAnalysis: {
increasing: false,
frequency: '1-2 per month',
hotspots: defect.location ? [defect.location.file] : ['src/handlers/'],
},
};
}
function generateRemediationPlan(
rootCause: RootCause,
factors: ContributingFactor[]
): RemediationPlan {
const immediateActions: RemediationAction[] = [
{
priority: 1,
action: `Fix the specific ${rootCause.category} issue at identified location`,
owner: 'Developer',
effort: 'low',
impact: 'high',
timeframe: '1-2 days',
},
];
const shortTermActions: RemediationAction[] = [
{
priority: 2,
action: 'Add regression test for this defect',
owner: 'QA',
effort: 'low',
impact: 'medium',
timeframe: '1 week',
},
{
priority: 3,
action: 'Review similar code paths for same issue',
owner: 'Tech Lead',
effort: 'medium',
impact: 'high',
timeframe: '2 weeks',
},
];
const longTermActions: RemediationAction[] = [
{
priority: 4,
action: 'Implement systematic validation layer',
owner: 'Architecture Team',
effort: 'high',
impact: 'high',
timeframe: '1 quarter',
},
];
// Add actions based on contributing factors
for (const factor of factors.filter((f) => f.severity === 'major')) {
shortTermActions.push({
priority: shortTermActions.length + 2,
action: `Address contributing factor: ${factor.description}`,
owner: factor.category === 'technical' ? 'Developer' : 'Manager',
effort: 'medium',
impact: 'medium',
timeframe: '2-4 weeks',
});
}
return {
immediateActions,
shortTermActions,
longTermActions,
estimatedEffort: '2-3 developer weeks',
riskIfUnaddressed: 'High - similar defects likely to recur, potential customer impact',
};
}
function generatePreventionMeasures(
rootCause: RootCause,
factors: ContributingFactor[]
): PreventionMeasure[] {
const measures: PreventionMeasure[] = [];
// Add measures based on root cause type
if (rootCause.type === 'code') {
measures.push({
measure: 'Add static analysis rule to detect this pattern',
type: 'tooling',
effectiveness: 0.85,
implementation: 'Configure ESLint/Semgrep with custom rule',
cost: 'low',
});
}
// Common prevention measures
measures.push(
{
measure: 'Enhance code review checklist with specific pattern',
type: 'code-review',
effectiveness: 0.75,
implementation: 'Update team code review guidelines',
cost: 'low',
},
{
measure: 'Add unit test template for this scenario',
type: 'testing',
effectiveness: 0.80,
implementation: 'Create test utilities and examples',
cost: 'medium',
},
{
measure: 'Conduct team training on defensive coding',
type: 'training',
effectiveness: 0.70,
implementation: 'Schedule workshop with examples',
cost: 'medium',
}
);
return measures.sort((a, b) => b.effectiveness - a.effectiveness);
}
function calculateOverallConfidence(rootConfidence: number, chainConfidences: number[]): number {
const avgChainConfidence =
chainConfidences.reduce((sum, c) => sum + c, 0) / chainConfidences.length;
const combined = rootConfidence * 0.6 + avgChainConfidence * 0.4;
return Math.round(combined * 100) / 100;
}
// Export tool definition for MCP registration
export const toolDefinition = {
name: 'aqe/analyze-root-cause',
description: 'Deep root cause analysis with causal chain identification and remediation planning',
category: 'defect-intelligence',
version: '3.2.3',
inputSchema: AnalyzeRootCauseInputSchema,
handler,
};
export default toolDefinition;