coulomb/markitect-main
Archived
2
0
Fork 0
Code Issues 135 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

chore: roadmap cleanup

Browse Source
This commit is contained in:
Bernd Worsch
2026-01-05 20:37:18 +01:00
parent 3003b9b8da
commit 5e147865f8
4 changed files with 5 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
roadmap/eat-the-frog/ISSUE_DATAMODEL_OPTIMIZATION_GAMEPLAN.md Normal file
View File

@@ -0,0 +1,316 @@
# Issue Datamodel Optimization Gameplan
## Executive Summary
Comprehensive plan to optimize the issue object datamodel based on the Datamodel Optimization Specialist Agent analysis. This gameplan implements proven optimization patterns to achieve model consistency, performance improvements, and code reduction.
## Current State Analysis
### Identified Datamodel Structure
**Core Models:**
- `/home/worsch/markitect_project/domain/issues/models.py` - Domain Issue, IssueState, Label, LabelCategories
- `/home/worsch/markitect_project/gitea/models.py` - API-focused Issue, Label, User, Milestone
- `/home/worsch/markitect_project/markitect/issues/activity_tracker.py` - IssueActivity, ActivityType
**Architecture Strengths:**
- Clean Architecture with domain separation
- Rich activity tracking with cost integration
- Plugin architecture for different backends (Gitea, Local)
- Well-defined repository interfaces
**Identified Issues:**
- Multiple Issue models causing inconsistencies
- Label-based state management complexity
- Missing convenience methods and properties
- Potential serialization inefficiencies
- No unified datamodel optimization approach
## Optimization Strategy
### PRIORITY 1: Unified Issue Model Architecture
**Goal**: Create single source of truth Issue model
**Implementation Plan:**
1. **Unified Issue Model** in `domain/issues/models.py`:
- Combine best features from domain and Gitea models
- Add external_id field for API mappings
- Implement cached label categorization for performance
- Add convenience properties for common operations
2. **Backward Compatibility Layer**:
- Create adapter classes for existing API interactions
- Maintain existing interfaces during transition
- Gradual migration path for all consumers
**Expected Benefits:**
- Single source of truth eliminates mapping complexity
- Consistent interface across all usage patterns
- Reduced maintenance overhead
### PRIORITY 2: Enhanced State Management
**Goal**: Unified state enum with mapping capabilities
**Implementation Plan:**
1. **Enhanced IssueState Enum**:
- Add mapping methods for string conversion
- Include display names for UI presentation
- Support for state transitions and validation
2. **State Management Service**:
- Centralized state transition logic
- Business rules enforcement
- Audit trail integration
**Expected Benefits:**
- Consistent state representations across layers
- Improved state validation and transitions
- Better UI/CLI presentation
### PRIORITY 3: Optimized Label System
**Goal**: 60-80% performance improvement in label processing
**Implementation Plan:**
1. **Unified Label Model**:
- Frozen dataclass for immutability
- Cached category detection using @cached_property
- Efficient value extraction methods
2. **Single-Pass Label Categorization**:
- Replace multiple iterations with single categorization
- Cache results for repeated access
- Optimized label filtering methods
**Expected Benefits:**
- Significant performance improvement in label operations
- Reduced memory usage through caching
- Cleaner label manipulation APIs
### PRIORITY 4: Enhanced Database Integration
**Goal**: Proper referential integrity and data consistency
**Implementation Plan:**
1. **Database Schema Enhancement**:
- Add issues table with proper constraints
- Implement foreign key relationships
- Create indices for performance
2. **Migration Strategy**:
- Create 002_issue_integration.sql migration
- Data integrity validation
- Rollback procedures
**Expected Benefits:**
- Data integrity through foreign key constraints
- Better query performance with proper indices
- Cleaner database structure
### PRIORITY 5: Repository Pattern Enhancement
**Goal**: High-performance repository with caching
**Implementation Plan:**
1. **Cached Repository Implementation**:
- TTL-based caching layer
- Efficient query patterns
- Bulk operation optimizations
2. **Query Optimization**:
- Label-based filtering improvements
- Pagination and sorting enhancements
- Connection pooling considerations
**Expected Benefits:**
- Improved application performance
- Reduced database load
- Better scalability for larger datasets
### PRIORITY 6: Activity Tracking Integration
**Goal**: Integrated activity tracking with issue lifecycle
**Implementation Plan:**
1. **Enhanced Activity Model**:
- Tight coupling with issue state changes
- Automated activity generation for lifecycle events
- Rich activity querying capabilities
2. **Lifecycle Integration**:
- Automatic activity logging on state changes
- Business logic triggers for activities
- Activity-driven notifications
**Expected Benefits:**
- Complete audit trail for all issue changes
- Automated activity tracking
- Better business intelligence capabilities
## Implementation Phases
### Phase 1: Model Unification (Week 1)
**Scope**: Create unified Issue model with backward compatibility
**Tasks:**
1. Analyze current Issue model usage patterns
2. Design unified Issue model with all required fields
3. Implement backward compatibility adapters
4. Create migration utilities
5. Update unit tests for new model
**Deliverables:**
- Enhanced `domain/issues/models.py` with unified Issue model
- Compatibility adapter classes
- Comprehensive test coverage
- Migration documentation
**Success Criteria:**
- All existing tests pass with adapter layer
- No breaking changes to external interfaces
- Performance benchmarks established
### Phase 2: Performance Optimization (Week 2)
**Scope**: Implement caching and optimize label processing
**Tasks:**
1. Implement cached label categorization
2. Add performance-optimized properties
3. Create repository caching layer
4. Optimize database queries
5. Add performance monitoring
**Deliverables:**
- Optimized label processing with caching
- High-performance repository implementation
- Database query optimizations
- Performance benchmark results
**Success Criteria:**
- 60-80% improvement in label processing performance
- Repository query response time improvements
- Memory usage optimization validated
### Phase 3: Integration Enhancement (Week 3)
**Scope**: Integrate activity tracking and enhance relationships
**Tasks:**
1. Enhance database schema with proper constraints
2. Integrate activity tracking with issue lifecycle
3. Implement cost allocation relationships
4. Add comprehensive validation
5. Create data migration scripts
**Deliverables:**
- Enhanced database schema with foreign keys
- Integrated activity tracking system
- Data validation framework
- Migration scripts and procedures
**Success Criteria:**
- Database integrity constraints properly enforced
- Activity tracking automatically captures all issue changes
- Data validation prevents inconsistent states
### Phase 4: Testing & Migration (Week 4)
**Scope**: Comprehensive testing and production deployment
**Tasks:**
1. Comprehensive integration testing
2. Performance benchmarking
3. Production data migration
4. Documentation updates
5. Training and knowledge transfer
**Deliverables:**
- Complete test suite with integration tests
- Performance benchmark reports
- Production migration procedures
- Updated documentation
- Training materials
**Success Criteria:**
- 100% test coverage for optimized models
- Performance improvements validated in production-like environment
- Successful data migration without data loss
- Team trained on new datamodel capabilities
## Risk Mitigation
### Technical Risks
1. **Backward Compatibility**: Maintain adapter layer during transition
2. **Data Integrity**: Comprehensive validation and migration scripts
3. **Performance Regression**: Extensive benchmarking and monitoring
4. **Complex Dependencies**: Careful dependency analysis and phased rollout
### Mitigation Strategies
1. **Gradual Migration**: Phase-by-phase implementation with rollback points
2. **Comprehensive Testing**: Unit, integration, and performance tests
3. **Monitoring**: Real-time performance and error monitoring
4. **Documentation**: Clear migration guides and troubleshooting procedures
## Success Metrics
### Quantitative Goals
- **Performance**: 60-80% improvement in label processing
- **Code Reduction**: 15-25 lines of code reduction per optimized model
- **Test Reliability**: 90%+ reduction in test failures due to model inconsistencies
- **Query Performance**: 50%+ improvement in database query response times
### Qualitative Goals
- **Maintainability**: Easier to modify and extend issue models
- **Developer Experience**: Cleaner APIs and more intuitive interfaces
- **Data Consistency**: Reliable data integrity across all operations
- **System Reliability**: Reduced bugs due to model inconsistencies
## Resource Requirements
### Development Team
- 1 Senior Developer (Lead optimization implementation)
- 1 Database Specialist (Schema and migration work)
- 1 QA Engineer (Testing and validation)
### Timeline
- **Total Duration**: 4 weeks
- **Effort Estimate**: ~6-8 person-weeks
- **Critical Path**: Phase 1 (Model Unification) → Phase 2 (Performance) → Phase 3 (Integration) → Phase 4 (Testing)
### Infrastructure
- Development and staging environments for testing
- Performance testing tools and monitoring
- Database migration and rollback capabilities
## Next Steps
### Immediate Actions (Next 1-2 Days)
1. **Team Alignment**: Review gameplan with development team
2. **Environment Setup**: Prepare development and testing environments
3. **Baseline Establishment**: Create performance and functionality baselines
4. **Detailed Planning**: Break down Phase 1 tasks into specific work items
### Week 1 Kickoff
1. Begin Phase 1 implementation
2. Set up continuous integration for new model testing
3. Establish performance monitoring baselines
4. Create detailed migration documentation
---
## Appendix
### Related Documents
- [Datamodel Optimization Specialist Agent Documentation](../docs/sub_agents/datamodel_optimizer.md)
- [Datamodel Optimizer Tool](../tools/datamodel_optimizer.py)
- [Issue #126 - IssueActivity Optimization Success Case](../docs/issues/issue_126_analysis.md)
### References
- Clean Architecture Principles
- Domain-Driven Design Patterns
- Database Design Best Practices
- Performance Optimization Techniques
---
*This gameplan provides a comprehensive roadmap for optimizing the issue datamodel while maintaining system stability, performance, and developer productivity. The phased approach ensures risk mitigation while delivering measurable improvements at each stage.*

5
roadmap/eat-the-frog/README.md Normal file
View File

@@ -0,0 +1,5 @@
This is a roadmap topic to swallow whatever leftovers should be done to clean things up regularly.
Before implementing the mixed bag of things should be revisited, organized and stuffed into a workplan
with a focus on cleanup with minimal effort. Big and interesting topics should get their own roadmap
topic directory.

75
roadmap/eat-the-frog/RelevantClaudeIssues.md Normal file
View File

@@ -0,0 +1,75 @@
# Relevant Claude Code Issues
## Introduction
This document tracks Claude Code issues that directly impact our development workflows for the MarkiTect project. Each issue section provides a clear problem description, affected workflows, related GitHub issues for monitoring, available workarounds, and resolution tracking information.
**Purpose:**
- Document blocking Claude Code issues affecting project development
- Provide centralized tracking of GitHub issues to monitor for fixes
- Maintain awareness of workarounds and their trade-offs
- Enable quick assessment of when normal workflows can resume
**Maintenance:**
- Update when new blocking issues are discovered
- Check GitHub issue status weekly and update resolution monitoring
- Remove resolved issues after confirming fixes work in our environment
- Maintained by the agent-claude-documentation subagent as part of issue tracking responsibilities
**🎯 CRITICAL WORKFLOW REMINDER:**
When discussing project issues (not Claude Code issues), ALWAYS fetch from Gitea first. Gitea is the source of truth for all issue assessment, feasibility evaluation, and implementation planning. Local files are insufficient for decision-making about issues. See ISSUE_WORKFLOW_REMINDER.md for complete workflow.
---
## Resolved Issues
### ✅ RESOLVED: Custom Subagents Not Available
### Problem Description (Historical)
Custom subagents defined in `.claude/agents/` directory were not being detected or made available as `subagent_type` options in the Task tool. This prevented the intended workflow of using specialized subagents for domain-specific tasks like project management, documentation, or Claude Code expertise.
The custom subagent system appeared completely broken, with agents not being recognized despite proper YAML frontmatter configuration.
### Resolution Details
**Resolved Date:** 2025-09-23
**Resolution Method:** Issue appears to have been fixed in current Claude Code version
**Verification:** Successfully tested the following subagents:
- ✅ `general-purpose` - Full tool access for complex multi-step tasks
- ✅ `agent-claude-documentation` - Specialized for Claude Code documentation and features
- ✅ `agent-project-management` - Specialized for MarkiTect project status and development planning
**Resolution Confirmation Steps:**
1. ✅ Custom agents now appear as valid `subagent_type` options in Task tool
2. ✅ Successfully invoked custom subagents for specialized tasks
3. ✅ All intended multi-agent workflows are now functional
4. ✅ No workarounds needed - normal operation restored
### Impact of Resolution
**Restored Workflows:**
- **Specialized Task Delegation**: ✅ Custom subagents working for domain-specific tasks
- **Project Management**: ✅ agent-project-management subagent functional for status tracking and planning
- **Documentation Assistance**: ✅ agent-claude-documentation subagent operational for Claude Code expertise
- **Task Decomposition**: ✅ Full subagent ecosystem available
- **Workflow Automation**: ✅ Multi-agent collaborative workflows enabled
**Workarounds No Longer Needed:**
- No need to downgrade Claude Code versions
- No need to use only built-in general-purpose agent
- No need for manual role assignment
### Related GitHub Issues (Historical Reference)
- [#4623](https://github.com/anthropics/claude-code/issues/4623) - Custom agents not being detected
- [#4728](https://github.com/anthropics/claude-code/issues/4728) - Agent discovery mechanism broken
- [#4626](https://github.com/anthropics/claude-code/issues/4626) - Custom agents missing from UI
- [#5185](https://github.com/anthropics/claude-code/issues/5185) - Agent configuration not working
- [#4182](https://github.com/anthropics/claude-code/issues/4182) - Task tool limitations for nested agents
---
## Monitoring Schedule
This document should be reviewed weekly to check for issue resolution and update status. The agent-claude-documentation subagent is responsible for maintaining this tracking and updating the project team when workflows can resume normal operation.