chore: history cleanup
This commit is contained in:
207
history/ADHOC_Main_Branch_Optimization_GAMEPLAN.md
Normal file
207
history/ADHOC_Main_Branch_Optimization_GAMEPLAN.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Main Branch Optimization Gameplan
|
||||
|
||||
## Executive Summary
|
||||
This gameplan provides a low-risk, incremental approach to optimizing the markitect project on the main branch. Each optimization is designed to be safe, reversible, and testable without requiring protective branching.
|
||||
|
||||
## Current State Analysis
|
||||
- **Directory Structure**: Hybrid layout with both root-level modules and `src/` structure
|
||||
- **Test Coverage**: 307 tests passing, good foundation
|
||||
- **Critical Issues**: Mock pollution creating 200+ directories, dual package structures
|
||||
- **Git Management**: Good .gitignore already in place
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Critical Infrastructure Cleanup (Zero Risk)
|
||||
|
||||
### 1.1 Mock Directory Cleanup (IMMEDIATE - HIGH PRIORITY)
|
||||
**Risk Level**: ⚪ Zero Risk
|
||||
**Impact**: 🔥 Critical
|
||||
**Duration**: 5 minutes
|
||||
|
||||
**Problem**: `MagicMock/Path.cwd().__truediv__()/` contains 200+ pollution directories
|
||||
**Action**: `rm -rf MagicMock/` (these are test artifacts)
|
||||
**Validation**:
|
||||
- Run full test suite before/after
|
||||
- Confirm no legitimate files are removed
|
||||
- Directory should not regenerate
|
||||
|
||||
### 1.2 Database File Management
|
||||
**Risk Level**: ⚪ Zero Risk
|
||||
**Impact**: 🟡 Low
|
||||
**Duration**: 2 minutes
|
||||
|
||||
**Problem**: `markitect.db` tracked in git (should be generated)
|
||||
**Action**:
|
||||
1. `git rm markitect.db`
|
||||
2. Add to .gitignore if not already present
|
||||
**Validation**: Database regenerates on first run
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Package Structure Rationalization (Low Risk)
|
||||
|
||||
### 2.1 Eliminate Dual Package Structure
|
||||
**Risk Level**: 🟡 Low Risk
|
||||
**Impact**: 🔥 High
|
||||
**Duration**: 15 minutes
|
||||
|
||||
**Problem**: Both root-level `markitect/` and `src/markitect/` exist
|
||||
**Strategy**: Keep root-level, remove `src/` (simpler imports)
|
||||
**Action**:
|
||||
1. Compare both package structures
|
||||
2. Merge any missing files from `src/` to root
|
||||
3. Remove `src/` directory
|
||||
4. Update any import references
|
||||
**Validation**: All tests pass, imports work correctly
|
||||
|
||||
### 2.2 Root-Level Module Organization
|
||||
**Risk Level**: 🟡 Low Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 10 minutes
|
||||
|
||||
**Problem**: Root-level modules mixed with package directories
|
||||
**Action**: Move standalone files into appropriate directories:
|
||||
- `tddai_cli.py` → `cli/tddai_cli.py` or `scripts/`
|
||||
- Shell scripts → `scripts/` directory
|
||||
**Validation**: Scripts still executable, paths updated
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Development Workflow Enhancement (Low Risk)
|
||||
|
||||
### 3.1 Test Organization Review
|
||||
**Risk Level**: 🟡 Low Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 20 minutes
|
||||
|
||||
**Problem**: Potential test duplication (282 vs 307 tests suggests missing tests)
|
||||
**Action**:
|
||||
1. Identify missing tests by comparing with feature branch
|
||||
2. Review for actual duplicate test cases
|
||||
3. Consolidate overlapping functionality
|
||||
**Validation**: Test count stabilizes, coverage maintained
|
||||
|
||||
### 3.2 Makefile Enhancement
|
||||
**Risk Level**: ⚪ Zero Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 10 minutes
|
||||
|
||||
**Current**: Basic Makefile exists
|
||||
**Action**: Add standard development targets:
|
||||
- `make clean` (remove artifacts)
|
||||
- `make test-quick` (fast test subset)
|
||||
- `make lint` (code quality)
|
||||
- `make check` (pre-commit checks)
|
||||
**Validation**: All targets work correctly
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Code Quality Infrastructure (Low Risk)
|
||||
|
||||
### 4.1 Import Organization
|
||||
**Risk Level**: 🟡 Low Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 15 minutes
|
||||
|
||||
**Problem**: Inconsistent import ordering
|
||||
**Action**:
|
||||
1. Add `isort` configuration to `pyproject.toml`
|
||||
2. Run `isort .` to standardize imports
|
||||
3. Add import checking to Makefile
|
||||
**Validation**: Imports consistent, tests pass
|
||||
|
||||
### 4.2 Code Formatting Standards
|
||||
**Risk Level**: 🟡 Low Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 10 minutes
|
||||
|
||||
**Action**:
|
||||
1. Add `black` configuration if not present
|
||||
2. Run formatting check
|
||||
3. Add formatting targets to Makefile
|
||||
**Validation**: Code style consistent
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Documentation Structure (Zero Risk)
|
||||
|
||||
### 5.1 Documentation Consolidation
|
||||
**Risk Level**: ⚪ Zero Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 15 minutes
|
||||
|
||||
**Problem**: Multiple gameplan docs in root
|
||||
**Action**:
|
||||
1. Create `docs/development/gameplans/` directory
|
||||
2. Move all `*_GAMEPLAN.md` files there
|
||||
3. Update references in main docs
|
||||
**Validation**: Documentation accessible, links work
|
||||
|
||||
### 5.2 README Optimization
|
||||
**Risk Level**: ⚪ Zero Risk
|
||||
**Impact**: 🟢 Medium
|
||||
**Duration**: 10 minutes
|
||||
|
||||
**Action**: Review and update README for current structure
|
||||
**Validation**: Setup instructions work for new users
|
||||
|
||||
---
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Execution Order (Strict Sequence)
|
||||
1. **Phase 1**: Must be done first (cleans critical issues)
|
||||
2. **Phase 2**: Core structure (foundation for later phases)
|
||||
3. **Phase 3**: Development workflow (builds on structure)
|
||||
4. **Phase 4**: Quality tools (requires stable structure)
|
||||
5. **Phase 5**: Documentation (final cleanup)
|
||||
|
||||
### Safety Protocols
|
||||
- **Test First**: Run full test suite before any change
|
||||
- **Single Change**: One optimization at a time
|
||||
- **Immediate Validation**: Test after each change
|
||||
- **Rollback Ready**: Use git commits for each step
|
||||
- **No Branching Required**: All changes safe enough for main
|
||||
|
||||
### Success Criteria
|
||||
- ✅ All 307 tests continue to pass
|
||||
- ✅ No functionality regression
|
||||
- ✅ Cleaner project structure
|
||||
- ✅ Improved developer experience
|
||||
- ✅ Better maintainability
|
||||
|
||||
### Estimated Total Time
|
||||
- **Phase 1**: 7 minutes (critical)
|
||||
- **Phase 2**: 25 minutes (structure)
|
||||
- **Phase 3**: 30 minutes (workflow)
|
||||
- **Phase 4**: 25 minutes (quality)
|
||||
- **Phase 5**: 25 minutes (docs)
|
||||
- **Total**: ~2 hours of focused work
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Before Starting
|
||||
1. Ensure clean git working directory
|
||||
2. Run test suite to confirm baseline
|
||||
3. Create backup branch if paranoid: `git branch backup-before-optimization`
|
||||
|
||||
### During Implementation
|
||||
1. Commit after each successful optimization
|
||||
2. If any test fails, immediately revert that change
|
||||
3. Never proceed with broken tests
|
||||
|
||||
### Rollback Strategy
|
||||
Each phase can be reverted independently:
|
||||
```bash
|
||||
git revert <commit-hash> # Revert specific optimization
|
||||
git reset --hard <commit> # Nuclear option to specific point
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
Start with **Phase 1.1** (Mock cleanup) - it's zero risk and high impact. The entire gameplan can be executed in a single session or spread across multiple sessions as time allows.
|
||||
|
||||
Each optimization builds value incrementally while maintaining project stability.
|
||||
Reference in New Issue
Block a user