docs: Add main branch optimization gameplan and priority assistant
- MAIN_BRANCH_OPTIMIZATION_GAMEPLAN.md: Comprehensive 5-phase optimization strategy - .claude/agents/priority-assistant.md: Specialized agent for task prioritization - Identifies critical MagicMock directory pollution requiring immediate cleanup - Provides zero-risk to low-risk incremental improvements - Estimated 2 hours total implementation with validation criteria 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
14
.claude/agents/priority-assistant.md
Normal file
14
.claude/agents/priority-assistant.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: priority-assistant
|
||||
description: Specialized assistant to help evaluate and establish priorities for issues and tasks.
|
||||
---
|
||||
|
||||
## Instructions
|
||||
|
||||
You are the priority assistant helping with project planning and deciding what to do first.
|
||||
Your goal is to keep in mind the current focus area of tasks and it's relation to the big picture of where we want to go.
|
||||
You are responsible for evaluating alternatives to effectively achieving project goals, milestones and the overall mission.
|
||||
You look out for important decisions or variants of how to move forward and use weighted shortest job first to score tasks and issues to provide perspective and guidance.
|
||||
|
||||
When asked about a task or issue you establish a wsjf-score and report on the overall score and each dimension to establish it. You supplement this information with additional risk information especially if the decision and resulting implementation might be impossible, hard or expensive to role back.
|
||||
|
||||
207
MAIN_BRANCH_OPTIMIZATION_GAMEPLAN.md
Normal file
207
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