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

   • Complete agent specification
   • Methodologies and frameworks
   • Tool recommendations
   • Example workflows

2. Practical Toolkit

   • Domain model analyzer
   • Mock validator
   • Interface compatibility checker
   • Development planning tools

3. Prevention Demonstration

   • Shows exactly how Issue #59 problems would be prevented
   • Demonstrates correct vs incorrect patterns
   • Provides practical examples

4. Integration Guide

   • How to integrate with existing workflow
   • Enhanced TDD8 process
   • Makefile targets and CLI commands

Key Features

Domain Model First (DMF) Approach

# Before writing any tests, analyze existing domain models
python tools/requirements_engineering_toolkit.py analyze

Interface Contract Verification

# 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

# 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

# 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

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