markitect-main/docs/integration/requirements_engineering_integration.md

Requirements Engineering Agent Integration Guide

Quick Start

Add these commands to your development workflow to prevent interface compatibility issues and mock object mismatches:

# Before starting any new feature
make validate-requirements

# When planning interface changes
python tools/requirements_engineering_toolkit.py plan-interface --interface YourInterface

# Before writing tests
python tools/requirements_engineering_toolkit.py checklist --feature "Your Feature"

# When creating mocks
python examples/issue_59_prevention_demo.py  # See correct patterns

Integration with Existing Workflow

1. Enhanced Makefile Targets

Add these targets to your Makefile:

# Requirements Engineering Integration
validate-requirements:
	@echo "🔍 Validating project requirements and foundations..."
	python tools/requirements_engineering_toolkit.py analyze

check-interface-compatibility:
	@echo "🔌 Checking interface compatibility..."
	python tools/requirements_engineering_toolkit.py plan-interface --interface $(INTERFACE)

generate-dev-checklist:
	@echo "📋 Generating development checklist..."
	python tools/requirements_engineering_toolkit.py checklist --feature "$(FEATURE)"

# Enhanced TDD workflow
tdd-start: validate-requirements
	@echo "🚀 Starting TDD workflow with requirements validation..."
	python tddai_cli.py tdd-start $(NUM)

# Pre-commit validation
pre-commit-validate:
	make validate-requirements
	python -m pytest tests/test_mock_compatibility.py -xvs

2. Enhanced TDD8 Workflow

The TDD8 workflow is enhanced with requirements engineering checkpoints:

1. ANALYZE     - Analyze existing domain models and interfaces
2. ISSUE       - Understand requirements in architectural context
3. TEST        - Write tests that match actual interfaces
4. RED         - Verify tests fail for the right reasons
5. GREEN       - Implement with interface compatibility
6. REFACTOR    - Maintain interface contracts
7. DOCUMENT    - Update interface documentation
8. PUBLISH     - Commit with interface change documentation

3. TodoWrite Integration

Enhanced TodoWrite with validation checkpoints:

# Example enhanced todo list
todos = [
    {
        "content": "Analyze existing domain models",
        "status": "pending",
        "activeForm": "Analyzing existing domain models",
        "checkpoint": "foundation_analysis"
    },
    {
        "content": "Define interface contracts",
        "status": "pending",
        "activeForm": "Defining interface contracts",
        "checkpoint": "interface_definition"
    },
    {
        "content": "Create spec-compliant mocks",
        "status": "pending",
        "activeForm": "Creating spec-compliant mocks",
        "checkpoint": "mock_validation"
    }
]

Pre-Development Checklist

Before starting any new feature development:

Foundation Analysis

• Run make validate-requirements
• Review existing domain models in target area
• Map current interface contracts
• Understand dependency relationships

Interface Planning

• Define new interface contracts
• Check compatibility with existing interfaces
• Plan evolution strategy for existing interfaces
• Document interface specifications

Test Strategy

• Plan test architecture that matches application architecture
• Identify domain models that will need mocking
• Plan integration test points
• Define validation checkpoints

Mock Object Guidelines

✅ Correct Mock Patterns

from unittest.mock import Mock
from domain.issues.models import Issue, IssueState, Label
from datetime import datetime, timezone

# CORRECT: Use spec= parameter
mock_issue = Mock(spec=Issue)
mock_issue.number = 59
mock_issue.title = "Test Issue"
mock_issue.state = IssueState.OPEN  # Use actual enum
mock_issue.labels = []
mock_issue.created_at = datetime.now(timezone.utc)
mock_issue.updated_at = datetime.now(timezone.utc)

❌ Incorrect Mock Patterns

# WRONG: No spec parameter
mock_issue = Mock()
mock_issue.number = 59
mock_issue.state = "open"  # String instead of enum!
# Missing required attributes

# WRONG: Assumption-based attributes
mock_issue.some_attribute_that_doesnt_exist = "value"

Mock Validation Script

Create tests/test_mock_compatibility.py:

import pytest
from unittest.mock import Mock
from domain.issues.models import Issue, IssueState
from datetime import datetime, timezone


class TestMockCompatibility:
    """Validate that test mocks match actual domain models."""

    def test_issue_mock_has_all_required_attributes(self):
        """Test that Issue mocks include all required attributes."""
        # Create a real Issue to get expected attributes
        real_issue = Issue(
            number=1,
            title="Real Issue",
            state=IssueState.OPEN,
            labels=[],
            created_at=datetime.now(timezone.utc),
            updated_at=datetime.now(timezone.utc)
        )

        # Create mock with spec
        mock_issue = Mock(spec=Issue)
        mock_issue.number = 1
        mock_issue.title = "Mock Issue"
        mock_issue.state = IssueState.OPEN
        mock_issue.labels = []
        mock_issue.created_at = datetime.now(timezone.utc)
        mock_issue.updated_at = datetime.now(timezone.utc)

        # Verify critical attributes match
        real_attrs = {attr for attr in dir(real_issue) if not attr.startswith('_')}
        mock_attrs = {attr for attr in dir(mock_issue) if not attr.startswith('_')}

        missing_attrs = real_attrs - mock_attrs
        critical_missing = [attr for attr in missing_attrs
                          if not callable(getattr(real_issue, attr))]

        assert not critical_missing, f"Mock missing critical attributes: {critical_missing}"

    def test_issue_mock_uses_correct_types(self):
        """Test that Issue mocks use correct types."""
        mock_issue = Mock(spec=Issue)
        mock_issue.state = IssueState.OPEN  # Should be enum, not string

        assert isinstance(mock_issue.state, IssueState), "State should be IssueState enum"

Interface Evolution Guidelines

Planning Interface Changes

1. Analyze Current Usage:

   # Find all usages of the interface
   grep -r "YourInterface" . --include="*.py"
   

2. Plan Backward Compatibility:

   # Example: Adding new method while maintaining compatibility
   class YourInterface(ABC):
       # Existing methods (don't change signatures)
       @abstractmethod
       def existing_method(self, param: str) -> str:
           pass
   
       # New methods (with default implementations if possible)
       def new_method(self, param: str) -> Optional[str]:
           """New method with default implementation for compatibility."""
           return None  # Safe default
   

3. Create Migration Plan:

   • Phase 1: Add new interface methods with defaults
   • Phase 2: Update implementations incrementally
   • Phase 3: Add deprecation warnings to old methods
   • Phase 4: Remove deprecated methods after transition period

Interface Compatibility Checking

# Check if new interface is compatible with existing implementations
python tools/requirements_engineering_toolkit.py plan-interface \
    --interface NewInterface \
    --existing-implementations ExistingRepo,AnotherRepo

Common Patterns and Solutions

Pattern 1: Plugin Interface Design

# Base interface that matches existing repository patterns
class IssueBackend(ABC):
    def __init__(self, config: Dict[str, Any]):
        self.config = config

    @abstractmethod
    def list_issues(self, state: Optional[str] = None) -> List[Issue]:
        pass

    @abstractmethod
    def get_issue(self, issue_id: str) -> Issue:
        pass

# Implementation that adapts async repository
class GiteaPlugin(IssueBackend):
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.repository = GiteaIssueRepository(self._create_connection_manager())

    def list_issues(self, state: Optional[str] = None) -> List[Issue]:
        # Adapter pattern: async -> sync
        return asyncio.run(self.repository.get_issues(state=state))

Pattern 2: Domain Model Extension

# Extending domain model while maintaining compatibility
@dataclass
class Issue:
    # Existing attributes (don't change order or remove)
    number: int
    title: str
    state: IssueState
    labels: List[Label]
    created_at: datetime
    updated_at: datetime

    # New attributes with defaults for backward compatibility
    body: str = ""
    assignees: List[str] = field(default_factory=list)
    html_url: str = ""

Pattern 3: Test Architecture Alignment

# Test structure that matches application architecture
class TestIssuePluginManager:
    def setup_method(self):
        # Use real domain models for mocks
        self.mock_issue = Mock(spec=Issue)
        self.mock_backend = Mock(spec=IssueBackend)

        # Configure mocks with realistic data
        self._configure_realistic_mocks()

    def _configure_realistic_mocks(self):
        """Configure mocks to match real object behavior."""
        self.mock_issue.number = 59
        self.mock_issue.state = IssueState.OPEN
        self.mock_issue.created_at = datetime.now(timezone.utc)
        # ... all required attributes

Error Prevention Checklist

Before Writing Tests

• Analyze target domain models with python tools/requirements_engineering_toolkit.py analyze
• Understand existing interface contracts
• Plan mock strategy using Mock(spec=ActualClass)
• Verify enum usage instead of strings

Before Implementation

• Check interface compatibility
• Plan async/sync adapter layers if needed
• Verify backward compatibility strategy
• Document interface contracts

Before Committing

• Run mock compatibility tests: pytest tests/test_mock_compatibility.py
• Validate interface evolution plan
• Check that no existing tests are broken
• Update documentation for interface changes

Troubleshooting Common Issues

Issue: Mock doesn't match domain model

Solution: Use Mock(spec=ActualClass) and include all required attributes

Issue: Enum vs string mismatch

Solution: Import and use actual enums: from domain.issues.models import IssueState

Issue: Async/sync interface mismatch

Solution: Add adapter layer to convert between async and sync interfaces

Issue: Missing attributes in mock

Solution: Run domain analysis to see all required attributes, ensure mock includes them

Issue: Interface breaking changes

Solution: Use evolution plan with backward compatibility and deprecation period

Integration with Existing Tools

CLI Commands

# Add to existing CLI
markitect validate-requirements    # Run foundation analysis
markitect check-interfaces        # Verify interface compatibility
markitect plan-migration          # Plan interface evolution
markitect validate-mocks          # Check mock compatibility

IDE Integration

• Add pre-commit hooks for requirements validation
• Configure IDE to run mock compatibility tests
• Set up interface change detection

CI/CD Integration

# Add to GitHub Actions / CI pipeline
- name: Validate Requirements
  run: make validate-requirements

- name: Check Mock Compatibility
  run: python -m pytest tests/test_mock_compatibility.py

This integration ensures that the Requirements Engineering Agent becomes a natural part of the development workflow, preventing the interface compatibility issues encountered in Issue #59 and improving overall code quality and development efficiency.