create_traceability_matrix

Instructions

Implementation Reference

• src/infrastructure/tools/ai-tasks/CreateTraceabilityMatrixTool.ts:40-115 (handler)

  Core handler function that executes the create_traceability_matrix tool logic, processing inputs to generate a traceability matrix using RequirementsTraceabilityService.

  async function executeCreateTraceabilityMatrix(args: CreateTraceabilityMatrixArgs): Promise<MCPResponse> {
    const traceabilityService = new RequirementsTraceabilityService();
  
    try {
      // Create mock PRD from content
      const mockPRD = {
        id: `prd-${args.projectId}`,
        title: `PRD for ${args.projectId}`,
        overview: args.prdContent.substring(0, 500),
        objectives: extractObjectivesFromContent(args.prdContent),
        successMetrics: extractSuccessMetricsFromContent(args.prdContent),
        features: args.features,
        author: 'system',
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
        aiGenerated: true,
        aiMetadata: {
          generatedBy: 'create-traceability-matrix',
          generatedAt: new Date().toISOString(),
          prompt: 'Extract PRD elements for traceability matrix',
          confidence: 0.8,
          version: '1.0.0'
        }
      };
  
      // Convert input tasks to AITask format
      const aiTasks = args.tasks.map(task => ({
        ...task,
        priority: task.priority as TaskPriority,
        complexity: task.complexity as TaskComplexity,
        status: TaskStatus.PENDING,
        dependencies: [],
        acceptanceCriteria: [],
        tags: [],
        aiGenerated: true,
        subtasks: [],
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString()
      }));
  
      // Create comprehensive traceability matrix
      const traceabilityMatrix = traceabilityService.createTraceabilityMatrix(
        args.projectId,
        mockPRD as any,
        args.features as any,
        aiTasks
      );
  
      // Validate completeness if requested
      let validation;
      if (args.validateCompleteness) {
        validation = validateTraceabilityCompleteness(traceabilityMatrix);
      }
  
      // Format response
      const summary = formatTraceabilityMatrixSummary(traceabilityMatrix, validation, args);
  
      return ToolResultFormatter.formatSuccess('create_traceability_matrix', {
        summary,
        traceabilityMatrix,
        validation,
        coverage: traceabilityMatrix.coverage,
        totalRequirements: traceabilityMatrix.businessRequirements.length,
        totalFeatures: traceabilityMatrix.features.length,
        totalUseCases: traceabilityMatrix.useCases.length,
        totalTasks: traceabilityMatrix.tasks.length
      });
  
    } catch (error) {
      process.stderr.write(`Error in create_traceability_matrix tool: ${error}\n`);
      return ToolResultFormatter.formatSuccess('create_traceability_matrix', {
        error: `Failed to create traceability matrix: ${error instanceof Error ? error.message : 'Unknown error'}`,
        success: false
      });
    }
  }

• src/infrastructure/tools/ai-tasks/CreateTraceabilityMatrixTool.ts:9-33 (schema)

  Zod schema defining the input parameters and validation for the create_traceability_matrix tool.

  const createTraceabilityMatrixSchema = z.object({
    projectId: z.string().describe('ID of the project to create traceability matrix for'),
    prdContent: z.string().min(100).describe('PRD content to extract business requirements from'),
    features: z.array(z.object({
      id: z.string(),
      title: z.string(),
      description: z.string(),
      priority: z.enum(['critical', 'high', 'medium', 'low']),
      userStories: z.array(z.string()),
      acceptanceCriteria: z.array(z.string()),
      estimatedComplexity: z.number().min(1).max(10)
    })).describe('List of features to include in traceability'),
    tasks: z.array(z.object({
      id: z.string(),
      title: z.string(),
      description: z.string(),
      complexity: z.number().min(1).max(10),
      estimatedHours: z.number(),
      priority: z.enum(['critical', 'high', 'medium', 'low'])
    })).describe('List of tasks to include in traceability'),
    includeUseCases: z.boolean().default(true).describe('Whether to generate use cases from features'),
    includeTraceabilityLinks: z.boolean().default(true).describe('Whether to generate traceability links'),
    includeCoverageAnalysis: z.boolean().default(true).describe('Whether to include coverage analysis'),
    validateCompleteness: z.boolean().default(true).describe('Whether to validate traceability completeness')
  });

• src/infrastructure/tools/ToolRegistry.ts:192-199 (registration)

  Registration of the createTraceabilityMatrixTool in the central ToolRegistry during initialization.

  this.registerTool(addFeatureTool);
  this.registerTool(generatePRDTool);
  this.registerTool(parsePRDTool);
  this.registerTool(getNextTaskTool);
  this.registerTool(analyzeTaskComplexityTool);
  this.registerTool(expandTaskTool);
  this.registerTool(enhancePRDTool);
  this.registerTool(createTraceabilityMatrixTool);

• src/index.ts:380-381 (registration)

  Dispatch handler in the main MCP server that routes call_tool requests for create_traceability_matrix to the execute function.

  case "create_traceability_matrix":
    return await executeCreateTraceabilityMatrix(args);

• src/infrastructure/tools/ai-tasks/CreateTraceabilityMatrixTool.ts:172-221 (helper)

  Helper function to validate the completeness of the generated traceability matrix, calculating coverage scores and identifying issues.

  function validateTraceabilityCompleteness(matrix: any): {
    isComplete: boolean;
    score: number;
    issues: string[];
    recommendations: string[];
  } {
    const issues = [];
    const recommendations = [];
    let score = 100;
  
    // Check coverage
    const coverage = matrix.coverage;
  
    if (coverage.orphanedTasks.length > 0) {
      issues.push(`${coverage.orphanedTasks.length} tasks have no requirements traceability`);
      score -= coverage.orphanedTasks.length * 5;
      recommendations.push('Link orphaned tasks to requirements or use cases');
    }
  
    if (coverage.unimplementedRequirements.length > 0) {
      issues.push(`${coverage.unimplementedRequirements.length} requirements have no implementing tasks`);
      score -= coverage.unimplementedRequirements.length * 10;
      recommendations.push('Create tasks to implement all requirements');
    }
  
    // Check use case coverage
    const useCaseCoverage = (coverage.useCasesCovered / matrix.useCases.length) * 100;
    if (useCaseCoverage < 90) {
      issues.push(`Only ${useCaseCoverage.toFixed(1)}% of use cases have implementing tasks`);
      score -= (90 - useCaseCoverage) / 2;
      recommendations.push('Ensure all use cases have implementing tasks');
    }
  
    // Check feature coverage
    const featureCoverage = (coverage.featuresCovered / matrix.features.length) * 100;
    if (featureCoverage < 95) {
      issues.push(`Only ${featureCoverage.toFixed(1)}% of features have use cases`);
      score -= (95 - featureCoverage) / 2;
      recommendations.push('Create use cases for all features');
    }
  
    score = Math.max(0, Math.min(100, score));
  
    return {
      isComplete: score >= 90 && issues.length === 0,
      score: Math.round(score),
      issues,
      recommendations
    };
  }