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