create_traceability_matrix

Generate a traceability matrix linking business requirements to features, use cases, and tasks with bidirectional tracking for project management.

Instructions

Create a comprehensive requirements traceability matrix linking PRD business requirements → features → use cases → tasks with full bidirectional traceability

Input Schema

TableJSON Schema

Name	Required	Description	Default
`projectId`	Yes
`prdContent`	Yes
`features`	Yes
`tasks`	Yes
`includeUseCases`	Yes
`includeTraceabilityLinks`	Yes
`includeCoverageAnalysis`	Yes
`validateCompleteness`	Yes

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
  };
}

MCP GitHub Project Manager