create_traceability_matrix

Generate a traceability matrix linking PRD 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)

The primary handler function that executes the tool's core logic: creates mock PRD, converts tasks, calls RequirementsTraceabilityService.createTraceabilityMatrix, validates completeness, and formats the output.

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 structure and validation for the create_traceability_matrix tool, including projectId, prdContent, features, tasks, and various boolean flags.

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:276-276 (registration)
Registration of the createTraceabilityMatrixTool in the central ToolRegistry singleton during initialization of built-in AI task management tools.
```
this.registerTool(createTraceabilityMatrixTool);
```
src/index.ts:462-463 (registration)
Dispatch case in the main MCP server tool handler switch statement that routes calls to the create_traceability_matrix tool to its execution function.
```
case "create_traceability_matrix":
  return await executeCreateTraceabilityMatrix(args);
```

src/services/RequirementsTraceabilityService.ts:283-326 (helper)

Core helper method in RequirementsTraceabilityService that builds the traceability matrix by extracting requirements from PRD, generating use cases, enhancing tasks with traceability info, creating links, and calculating coverage metrics.

createTraceabilityMatrix(
  projectId: string,
  prd: PRDDocument,
  features: FeatureRequirement[],
  tasks: AITask[]
): TraceabilityMatrix {
  // Extract business requirements from PRD
  const businessRequirements = this.extractBusinessRequirementsFromPRD(prd);

  // Generate use cases from features
  const useCases = features.flatMap(feature =>
    this.generateUseCasesFromFeature(feature, businessRequirements)
  );

  // Enhance tasks with traceability
  const enhancedTasks = this.enhanceTasksWithTraceability(
    tasks, useCases, features, businessRequirements, prd.id
  );

  // Create traceability links
  const traceabilityLinks = this.generateTraceabilityLinks(
    businessRequirements, features, useCases, enhancedTasks
  );

  // Calculate coverage
  const coverage = this.calculateCoverage(
    businessRequirements, features, useCases, enhancedTasks
  );

  return {
    id: `tm-${projectId}-${Date.now()}`,
    projectId,
    prdId: prd.id,
    businessRequirements,
    features: features as EnhancedFeatureRequirement[], // Type assertion for now
    useCases,
    tasks: enhancedTasks,
    traceabilityLinks,
    coverage,
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
    version: '1.0.0'
  };
}

mcp-github-project-manager