create_traceability_matrix
Generate a traceability matrix to link PRD requirements, features, use cases, and tasks, enabling bidirectional tracking, coverage analysis, and completeness validation for GitHub 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 |
|---|---|---|---|
| features | Yes | ||
| includeCoverageAnalysis | Yes | ||
| includeTraceabilityLinks | Yes | ||
| includeUseCases | Yes | ||
| prdContent | Yes | ||
| projectId | Yes | ||
| tasks | Yes | ||
| validateCompleteness | Yes |
Implementation Reference
- Main handler function that implements the core logic of the 'create_traceability_matrix' tool. It processes input arguments, creates a mock PRD, generates AI tasks, calls RequirementsTraceabilityService to build the matrix, performs validation, and formats the response.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 }); } }
- 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:275-276 (registration)Registration of the createTraceabilityMatrixTool in the central ToolRegistry during initialization of built-in tools.this.registerTool(enhancePRDTool); this.registerTool(createTraceabilityMatrixTool);
- src/index.ts:462-463 (registration)Dispatch handler in the main server that routes 'create_traceability_matrix' tool calls to the executeCreateTraceabilityMatrix function.case "create_traceability_matrix": return await executeCreateTraceabilityMatrix(args);
- Helper function that formats the traceability matrix results into a detailed markdown summary used in the tool response.function formatTraceabilityMatrixSummary( matrix: any, validation: any, args: CreateTraceabilityMatrixArgs ): string { const sections = [ '# Requirements Traceability Matrix Created', '', `## Project: ${args.projectId}`, `**Matrix ID:** ${matrix.id}`, `**Created:** ${new Date(matrix.createdAt).toLocaleString()}`, `**Version:** ${matrix.version}`, '' ]; // Hierarchy overview sections.push( '## Requirements Hierarchy', `**Business Requirements:** ${matrix.businessRequirements.length}`, `**Features:** ${matrix.features.length}`, `**Use Cases:** ${matrix.useCases.length}`, `**Tasks:** ${matrix.tasks.length}`, `**Traceability Links:** ${matrix.traceabilityLinks.length}`, '' ); // Coverage analysis const coverage = matrix.coverage; sections.push( '## Traceability Coverage', `**Business Requirements Covered:** ${coverage.businessRequirementsCovered}/${matrix.businessRequirements.length} (${Math.round((coverage.businessRequirementsCovered/matrix.businessRequirements.length)*100)}%)`, `**Features with Use Cases:** ${coverage.featuresCovered}/${matrix.features.length} (${Math.round((coverage.featuresCovered/matrix.features.length)*100)}%)`, `**Use Cases with Tasks:** ${coverage.useCasesCovered}/${matrix.useCases.length} (${Math.round((coverage.useCasesCovered/matrix.useCases.length)*100)}%)`, `**Tasks with Traceability:** ${coverage.tasksWithTraceability}/${matrix.tasks.length} (${Math.round((coverage.tasksWithTraceability/matrix.tasks.length)*100)}%)`, '' ); // Issues and gaps if (coverage.orphanedTasks.length > 0) { sections.push( '### ⚠️ Orphaned Tasks (No Requirements Link)', ...coverage.orphanedTasks.slice(0, 5).map((taskId: string) => { const task = matrix.tasks.find((t: any) => t.id === taskId); return `- ${task?.title || taskId}`; }), coverage.orphanedTasks.length > 5 ? `... and ${coverage.orphanedTasks.length - 5} more` : '', '' ); } if (coverage.unimplementedRequirements.length > 0) { sections.push( '### ⚠️ Unimplemented Requirements', ...coverage.unimplementedRequirements.slice(0, 5).map((reqId: string) => { const req = matrix.businessRequirements.find((r: any) => r.id === reqId); return `- ${req?.title || reqId}`; }), coverage.unimplementedRequirements.length > 5 ? `... and ${coverage.unimplementedRequirements.length - 5} more` : '', '' ); } // Validation results if (validation) { sections.push( '## Validation Results', `**Completeness Score:** ${validation.score}/100`, `**Status:** ${validation.isComplete ? '✅ Complete' : '⚠️ Needs Attention'}`, '' ); if (validation.issues.length > 0) { sections.push( '**Issues Found:**', ...validation.issues.map((issue: string) => `- ${issue}`), '' ); } if (validation.recommendations.length > 0) { sections.push( '**Recommendations:**', ...validation.recommendations.map((rec: string) => `- ${rec}`), '' ); } } // Sample traceability paths sections.push( '## Sample Traceability Paths', '' ); // Show a few complete traceability paths matrix.businessRequirements.slice(0, 3).forEach((req: any, index: number) => { const relatedFeatures = matrix.features.filter((f: any) => matrix.traceabilityLinks.some((link: any) => link.fromRequirementId === req.id && link.toRequirementId === f.id ) ); if (relatedFeatures.length > 0) { const feature = relatedFeatures[0]; const relatedUseCases = matrix.useCases.filter((uc: any) => uc.parentFeatureId === feature.id); const relatedTasks = matrix.tasks.filter((task: any) => task.implementsFeatures.includes(feature.id)); sections.push( `### Path ${index + 1}: ${req.title}`, `**Business Requirement** → **Feature:** ${feature.title}`, relatedUseCases.length > 0 ? `**Feature** → **Use Case:** ${relatedUseCases[0].title}` : '', relatedTasks.length > 0 ? `**Use Case** → **Task:** ${relatedTasks[0].title}` : '', '' ); } }); // Next steps sections.push( '## Next Steps', '1. Review and address any orphaned tasks or unimplemented requirements', '2. Use the traceability matrix to track requirement changes', '3. Update task progress and verify requirement implementation', '4. Use traceability for impact analysis when requirements change', '5. Generate test cases based on use cases and acceptance criteria', '' ); // Related commands sections.push( '## Related Commands', '- `validate_requirements` - Validate requirement completeness', '- `track_requirement_changes` - Track changes to requirements', '- `generate_test_cases` - Generate test cases from use cases', '- `analyze_impact` - Analyze impact of requirement changes' ); return sections.join('\n'); }