markitect-main/docs/sub_agents/README.md

# Requirements Engineering and Incremental Development Planning Sub-Agent

## Executive Summary

This specialized sub-agent was designed to prevent the interface compatibility issues and mock object mismatches encountered during Issue #59 debugging session. It provides a systematic approach to requirements engineering that ensures solid foundations before implementation.

## Problem Analysis: What Went Wrong in Issue #59

During the Issue #59 debugging session, several critical problems were identified:

### 1. Mock Object Mismatches
- Tests created `Mock()` objects without `spec=` parameter
- Mock attributes didn't match actual domain model attributes
- Used strings instead of enums (e.g., `state = "open"` instead of `IssueState.OPEN`)
- Missing required attributes like `created_at`, `updated_at`

### 2. Interface Compatibility Issues
- Tests assumed interface methods that didn't exist in actual implementation
- Async/sync mismatch between repository (async) and expected interface (sync)
- Parameter type mismatches (string vs int for issue IDs)

### 3. Bottom-Up Structure Problems
- Tests written without understanding existing domain model structure
- Assumptions made about interface contracts without verification
- No analysis of existing infrastructure before adding new layers

### 4. Integration Planning Failures
- No clear plan for how new CLI would integrate with existing infrastructure
- Missing adapter layers between async repositories and sync interfaces
- No backward compatibility strategy

## Solution: Requirements Engineering Agent

### Core Components

1. **[Requirements Engineering Agent Documentation](requirements_engineering_agent.md)**
   - Complete agent specification
   - Methodologies and frameworks
   - Tool recommendations
   - Example workflows

2. **[Practical Toolkit](../tools/requirements_engineering_toolkit.py)**
   - Domain model analyzer
   - Mock validator
   - Interface compatibility checker
   - Development planning tools

3. **[Prevention Demonstration](../examples/issue_59_prevention_demo.py)**
   - Shows exactly how Issue #59 problems would be prevented
   - Demonstrates correct vs incorrect patterns
   - Provides practical examples

4. **[Integration Guide](../docs/integration/requirements_engineering_integration.md)**
   - How to integrate with existing workflow
   - Enhanced TDD8 process
   - Makefile targets and CLI commands

### Key Features

#### Domain Model First (DMF) Approach
```bash
# Before writing any tests, analyze existing domain models
python tools/requirements_engineering_toolkit.py analyze
```

#### Interface Contract Verification
```python
# Ensure mocks match actual domain models
mock_issue = Mock(spec=Issue)  # ✅ Use spec=
mock_issue.state = IssueState.OPEN  # ✅ Use actual enum
```

#### Incremental Architecture Validation
- Checkpoint-based development
- Interface compatibility checking
- Mock validation at each step

#### Foundation Assessment
- Map existing interfaces before adding new ones
- Understand dependency relationships
- Plan integration points

## Practical Usage

### Quick Start Commands

```bash
# 1. Before starting any new feature
make validate-requirements

# 2. Plan interface evolution
python tools/requirements_engineering_toolkit.py plan-interface --interface YourInterface

# 3. Generate development checklist
python tools/requirements_engineering_toolkit.py checklist --feature "Your Feature"

# 4. Validate test mocks
python tools/requirements_engineering_toolkit.py validate-mocks --test-file tests/your_test.py
```

### Enhanced TDD8 Workflow

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 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

### Integration with Existing Workflow

#### Makefile Enhancement
```makefile
# Add requirements validation to existing workflow
tdd-start: validate-requirements
	python tddai_cli.py tdd-start $(NUM)

validate-requirements:
	python tools/requirements_engineering_toolkit.py analyze
```

#### Pre-commit Validation
```bash
# Add to pre-commit hooks
make validate-requirements
python -m pytest tests/test_mock_compatibility.py
```

## Specific Issue #59 Prevention

The agent would have prevented Issue #59 problems through:

### 1. Foundation Analysis
- Would have discovered actual `Issue` domain model structure
- Would have identified `IssueState` enum vs string requirement
- Would have mapped existing `GiteaIssueRepository` interface

### 2. Interface Planning
- Would have identified async/sync mismatch between repository and plugin interface
- Would have planned adapter layer needed
- Would have defined clear interface contracts

### 3. Mock Validation
- Would have enforced `Mock(spec=Issue)` usage
- Would have caught attribute mismatches before running tests
- Would have ensured enum usage instead of strings

### 4. Integration Strategy
- Would have planned how CLI integrates with existing infrastructure
- Would have identified reusable components
- Would have maintained backward compatibility

## Benefits

### Development Efficiency
- **Reduced Debugging Time**: Catch interface issues before implementation
- **Faster Development**: Clear development path with validated foundations
- **Better Architecture**: Planned evolution with backward compatibility

### Code Quality
- **Interface Consistency**: All interfaces match actual implementations
- **Type Safety**: Proper use of enums and type hints
- **Test Reliability**: Mocks that match real objects

### Risk Mitigation
- **Early Problem Detection**: Find compatibility issues during planning
- **Backward Compatibility**: Ensure changes don't break existing code
- **Integration Safety**: Validate all integration points

## Implementation Status

### Completed Components
- ✅ Agent specification and methodology
- ✅ Practical toolkit implementation
- ✅ Prevention demonstration
- ✅ Integration guide
- ✅ Documentation and examples

### Ready for Integration
- ✅ Makefile targets defined
- ✅ CLI commands specified
- ✅ Test patterns documented
- ✅ Workflow enhancements planned

### Next Steps
1. Add Makefile targets to existing workflow
2. Create mock compatibility test suite
3. Integrate with TDD8 process
4. Train development team on usage patterns

## Files and Documentation

```
docs/sub_agents/
├── README.md                                    # This overview
├── requirements_engineering_agent.md           # Complete agent specification
└── integration/
    └── requirements_engineering_integration.md # Integration guide

tools/
└── requirements_engineering_toolkit.py         # Practical implementation

examples/
└── issue_59_prevention_demo.py                # Prevention demonstration

tests/
└── test_mock_compatibility.py                 # Mock validation tests (to be created)
```

## Conclusion

The Requirements Engineering and Incremental Development Planning Sub-Agent provides a comprehensive solution to prevent the interface compatibility issues encountered in Issue #59. By implementing systematic foundation analysis, interface contract verification, and mock validation, it ensures that development builds on solid foundations rather than incorrect assumptions.

The agent integrates seamlessly with existing TDD8 workflow and provides practical tools that make requirements engineering a natural part of the development process. This leads to better architecture, fewer bugs, and more efficient development.