requirement-comparison-reporter

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](references/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](references/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](references/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 test