requirement-comparison-reporter

name

requirement-comparison-reporter

description

Compares old and new requirement documents, analyzes code repository impact, and generates detailed modification plans. Use when Claude needs to: (1) Compare requirement versions and identify changes, (2) Map requirement changes to code components, (3) Identify components to modify, delete, or add, (4) Analyze dependencies and integration points, (5) Assess test impact, (6) Generate comprehensive modification plans in Markdown format. Supports text/Markdown requirements and analyzes feature-level, functional, and API changes.

Requirement Comparison Reporter

Generate detailed modification plans by comparing requirement documents and analyzing code impact.

Workflow

1. Understand the Inputs

Gather required inputs:

• Old requirement document (path or content)
• New requirement document (path or content)
• Repository path

Verify inputs:

• Requirements are readable (text/Markdown format)
• Repository path is valid
• Repository contains Python code

2. Analyze Requirement Changes

Read both requirement documents:

• Extract key sections and features
• Identify structure and organization
• Note any explicit requirement IDs or labels

Compare requirements:

Identify added requirements:

• Features present in new but not in old
• New functionality descriptions
• New API endpoints or interfaces
• New business rules

Identify modified requirements:

• Features with changed descriptions
• Updated acceptance criteria
• Modified API contracts
• Changed business logic

Identify removed requirements:

• Features present in old but not in new
• Deprecated functionality
• Removed API endpoints

Categorize changes:

• Feature-level changes (new/modified/removed features)
• Functional changes (behavior, logic, workflows)
• API changes (endpoints, parameters, responses)

See analysis-patterns.md for detailed comparison strategies.

3. Analyze Code Structure

Automated analysis:

python scripts/analyze_code_impact.py <repo_path>

Manual analysis:

• Identify main modules and packages
• Locate key classes and functions
• Understand code organization
• Find test directory structure

Build component inventory:

• List all modules with their classes and functions
• Note public vs private components
• Identify entry points and main functionality
• Map test files to source files

4. Map Requirements to Code

For each requirement change, identify affected code:

Name-based mapping:

• Match requirement terms to class/function names
• Look for modules named after features
• Find components with related naming

Comment-based mapping:

• Search for requirement references in comments
• Look for issue/ticket numbers
• Find explicit requirement mentions

Functionality-based mapping:

• Analyze what each component does
• Match functionality to requirements
• Use docstrings to understand purpose

Test-based mapping:

• Use test names to infer functionality
• Map test files to requirements
• Associate test cases with features

Example mapping:

Requirement: "Add user authentication"
→ Likely components:
  - auth.py or authentication.py
  - user.py (User class)
  - login-related functions
  - test_auth.py or test_authentication.py

5. Identify Components to Modify

For modified requirements:

Determine modification type:

• Behavior change (logic modification)
• Signature change (parameters, return values)
• Integration change (new dependencies)

Identify affected components:

• Primary components implementing the feature
• Helper functions used by primary components
• Configuration or constants

Assess complexity:

• Simple: Single function/method change
• Medium: Multiple related changes
• Complex: Architectural or widespread changes

Example:

### Modified Requirement: User login now requires 2FA

**Components to Modify:**
- `auth.py::AuthManager.login()` - Add 2FA verification step
- `user.py::User` - Add 2FA token field
- `config.py` - Add 2FA configuration

**Complexity:** Medium

6. Identify Components to Delete

For removed requirements:

Find components to delete:

• Modules implementing removed features
• Classes specific to removed functionality
• Functions no longer needed

Check for dependencies:

• Identify components that depend on code to be deleted
• Determine if dependencies can be safely removed
• Plan for updating dependent code

Example:

### Removed Requirement: Legacy XML export

**Components to Delete:**
- `export/xml_exporter.py` - Entire module
- `utils/xml_helpers.py` - Helper functions

**Dependent Components:**
- `export/exporter.py` - Remove XML export option

7. Identify Components to Add

For new requirements:

Determine what needs to be created:

• New modules for new feature areas
• New classes for new entities
• New functions for new operations

Recommend dependencies:

• Identify existing components that can be reused
• Suggest appropriate base classes
• Recommend utility functions to use

Plan integration:

• Determine where new code fits in architecture
• Identify integration points with existing code
• Plan API or interface design

Example:

### New Requirement: Email notifications

**Components to Add:**
- `notifications/email_notifier.py` - New module
  - Class: EmailNotifier
  - Methods: send_email(), format_template()

**Recommended Dependencies:**
- `notifications/base_notifier.py` - Base class
- `user.py` - Get user email addresses
- `templates/` - Email templates

**Integration Points:**
- Called by: event handlers in `events.py`
- Configured in: `config.py`

See analysis-patterns.md for detailed patterns.

8. Analyze Test Impact

For each code change, identify test impact:

Tests to modify:

• Tests for components being modified
• Integration tests involving changed components
• Tests with changed assertions or expectations

Tests to delete:

• Tests for removed components
• Tests for deprecated functionality

Tests to add:

• Tests for new components
• Tests for new behavior in modified components
• Integration tests for new features

Example:

### Test Impact for User Authentication Changes

**Tests to Modify:**
- `test_auth.py::test_login()` - Add 2FA verification
- `test_user.py::test_user_creation()` - Add 2FA field

**Tests to Add:**
- `test_auth.py::test_login_with_2fa()` - New test
- `test_auth.py::test_2fa_token_validation()` - New test

9. Analyze Dependencies

Build dependency graph:

• Identify what each component depends on
• Find components that depend on each component
• Map import relationships

For new components:

• Recommend existing components to depend on
• Identify reusable utilities
• Suggest appropriate base classes

For modified components:

• Check if changes affect dependent components
• Identify ripple effects
• Plan for updating dependents

For deleted components:

• Find all components that import deleted code
• Plan for removing or updating imports
• Identify alternative components to use

10. Generate Modification Plan

Create comprehensive report using template:

See report-template.md for full template.

Report structure:

1. Executive Summary

• Total changes count
• Impact summary
• Complexity assessment

2. Requirement Changes

• Added requirements with impact
• Modified requirements with changes
• Removed requirements with impact

3. Code Impact Analysis

• Components to modify (with details)
• Components to delete (with dependencies)
• Components to add (with recommendations)

4. Test Impact Analysis

• Tests to modify
• Tests to delete
• Tests to add

5. Dependency Analysis

• New dependencies required
• Dependency changes
• Removed dependencies

6. Modification Plan

• Phase 1: Preparation
• Phase 2: Deletions
• Phase 3: Modifications
• Phase 4: Additions
• Phase 5: Integration Testing
• Phase 6: Documentation

7. Risk Assessment

• High-risk changes
• Mitigation strategies

8. Recommendations

• Implementation recommendations
• Architecture recommendations
• Testing recommendations

9. Appendix

• Requirement traceability matrix
• Component dependency graph
• Glossary

11. Review and Refine

Verify completeness:

• All requirement changes addressed
• All affected components identified
• All dependencies analyzed
• All tests considered

Check accuracy:

• Component names and paths correct
• Dependency relationships accurate
• Complexity assessments reasonable
• Recommendations actionable

Refine report:

• Clarify ambiguous sections
• Add missing details
• Improve recommendations
• Ensure consistency

Output Format

Generate a Markdown report with the following sections:

# Requirement Comparison Report

## Executive Summary
[High-level overview of changes and impact]

## Requirement Changes
### Added Requirements
[List with impact analysis]

### Modified Requirements
[List with before/after comparison]

### Removed Requirements
[List with deletion impact]

## Code Impact Analysis
### Components to Modify
[Detailed list with reasons and complexity]

### Components to Delete
[List with dependency impact]

### Components to Add
[List with structure and dependencies]

## Test Impact Analysis
[Tests to modify, delete, and add]

## Dependency Analysis
[New, modified, and removed dependencies]

## Modification Plan
[Phased implementation plan]

## Risk Assessment
[Risks and mitigation strategies]

## Recommendations
[Actionable recommendations]

## Appendix
[Traceability matrix, dependency graph, glossary]

Best Practices

Requirement Analysis

• Read both documents thoroughly
• Focus on meaningful changes, not just wording
• Categorize changes clearly
• Note ambiguities or unclear changes

Code Mapping

• Use multiple mapping strategies
• Verify mappings with code inspection
• Consider indirect relationships
• Document mapping rationale

Impact Analysis

• Consider both direct and indirect impact
• Analyze ripple effects
• Assess test coverage impact
• Evaluate dependency changes

Planning

• Break down into manageable phases
• Prioritize by risk and dependency
• Provide clear, actionable steps
• Include verification checkpoints

Reporting

• Be specific and detailed
• Use clear, consistent terminology
• Provide code references (file:line)
• Include examples where helpful

Common Scenarios

Scenario 1: API Endpoint Changes

Input:

• Old req: GET /users returns all fields
• New req: GET /users returns limited fields, add GET /users/detailed

Analysis:

• Modified: routes/users.py::get_users() - Limit fields
• Added: routes/users.py::get_users_detailed() - New endpoint
• Tests: Modify existing, add new tests

Scenario 2: Feature Removal

Input:

• Old req: Support XML export
• New req: XML export removed

Analysis:

• Delete: export/xml_exporter.py
• Modify: export/exporter.py - Remove XML option
• Tests: Delete XML export tests

Scenario 3: New Feature Addition

Input:

• Old req: Basic notifications
• New req: Add email notifications

Analysis:

• Add: notifications/email_notifier.py
• Depends on: notifications/base_notifier.py, user.py
• Tests: Add comprehensive email notification tests

Troubleshooting

Issue: Can't map requirement to code

Solution:

• Search for related keywords in codebase
• Check test files for clues
• Look for similar functionality
• Ask user for guidance

Issue: Unclear requirement change

Solution:

• Highlight ambiguity in report
• Provide multiple interpretations
• Request clarification
• Make reasonable assumptions and document them

Issue: Complex dependency graph

Solution:

• Focus on direct dependencies first
• Identify critical paths
• Simplify visualization
• Provide summary and details separately

Issue: Large number of changes

Solution:

• Prioritize by impact and risk
• Group related changes
• Use summary sections
• Provide detailed appendix