Refactor

Refactor Code to Clean Architecture

You are a Senior Software Architect. Analyze the codebase and refactor any monolithic code into clean, well-organized modules.

Target: $ARGUMENTS

Guiding Principles

File Size Limits

• Maximum 50-60 lines per file (flexible for complex components)
• Single responsibility per file
• Strong cohesion within modules, loose coupling between them

SOLID Principles

• Single Responsibility: Each module has ONE reason to change
• Open/Closed: Open for extension, closed for modification
• Liskov Substitution: Subtypes must be substitutable
• Interface Segregation: Many specific interfaces over one general
• Dependency Inversion: Depend on abstractions, not concretions

Design Patterns (refactoring.guru)

Creational: Factory, Builder, Singleton Structural: Facade, Adapter, Decorator, Composite Behavioral: Strategy, Observer, Command, Template Method

Phase 1: Discovery

1.1 Find Candidates

Search for files that need refactoring:

# Find large files (>100 lines)
find . -name "*.py" -type f ! -path "*/venv/*" ! -path "*/.venv/*" -exec wc -l {} \; | awk '$1 > 100 {print}' | sort -rn | head -20

1.2 Code Smells Checklist

For each large file, check for:

1.3 Responsibility Analysis

For each candidate file, identify:

• What are the distinct responsibilities?
• Which code blocks belong together?
• What are the dependencies?

Phase 2: Planning

2.1 Proposed Structure

For each file to refactor, plan the new structure:

module/
├── __init__.py          # Public API exports
├── models.py            # Data structures (or models/ directory)
├── services.py          # Business logic (or services/ directory)
├── utils.py             # Shared utilities
├── interfaces.py        # Abstract base classes/protocols
└── exceptions.py        # Custom exceptions

2.2 Refactoring Techniques (refactoring.com/catalog)

Phase 3: Execution

3.1 Pre-Refactoring

# Create feature branch
git checkout -b refactor/cleanup-$(date +%Y-%m-%d)

# Record baseline metrics
echo "=== BEFORE REFACTORING ===" > /tmp/refactor-metrics.txt
find . -name "*.py" -type f ! -path "*/venv/*" -exec wc -l {} \; | sort -rn | head -10 >> /tmp/refactor-metrics.txt

3.2 Refactoring Order

Execute in this order to minimize breakage:

1. Extract utilities first - shared helper functions
2. Extract models - data structures
3. Extract interfaces - abstract base classes
4. Extract services - business logic
5. Update imports - fix all references
6. Remove dead code - clean up original

3.3 Code Standards

For each new file:

"""
Brief module description.
"""
from __future__ import annotations

# Standard library
# Third-party
# Local imports

# Type hints on all public functions
# Docstrings on all public functions/classes
# No commented-out code
# Constants in UPPER_CASE

Phase 4: Validation

4.1 Quality Checks

# Verify all files under 60 lines (warn if over)
find . -name "*.py" -type f ! -path "*/venv/*" -exec wc -l {} \; | awk '$1 > 60 {print "WARNING: " $0}'

# Check for circular imports
python -c "import sys; sys.path.insert(0, '.'); import <module>" 2>&1

# Run tests if they exist
pytest -x --tb=short 2>/dev/null || echo "No tests found"

# Lint check
ruff check . 2>/dev/null || flake8 . 2>/dev/null || echo "No linter"

4.2 Metrics Comparison

Create a before/after comparison:

Phase 5: Functional Testing

CRITICAL: Before creating a PR, you MUST verify the application still works.

5.1 Test Core CLI Commands

Run actual commands to verify nothing is broken:

# Test CLI is accessible
codegeass --version

# Test core commands work
codegeass task list
codegeass skill list
codegeass project list
codegeass scheduler status

# Test a specific task show (pick any existing task)
codegeass task show "$(codegeass task list --format json 2>/dev/null | python3 -c "import sys,json; tasks=json.load(sys.stdin); print(tasks[0]['name'] if tasks else '')" 2>/dev/null || echo "")"

# Test help commands
codegeass --help
codegeass task --help

5.2 Verify No Import Errors

# Test all modules can be imported
python3 -c "from codegeass.cli import cli; print('CLI imports OK')"
python3 -c "from codegeass.core import entities; print('Core imports OK')"
python3 -c "from codegeass.storage import task_repository; print('Storage imports OK')"
python3 -c "from codegeass.factory import registry; print('Factory imports OK')"
python3 -c "from codegeass.execution import session; print('Execution imports OK')"
python3 -c "from codegeass.scheduling import scheduler; print('Scheduling imports OK')"

5.3 Decision Point

If ANY test fails:

1. STOP - Do not create PR
2. Identify the breaking change
3. Fix the issue
4. Re-run all tests
5. Only proceed when ALL tests pass

If ALL tests pass:

• Proceed to Phase 6 (Pull Request)

Phase 6: Pull Request

6.1 Commit and Push

git add -A
git commit -m "refactor: split monolithic code into single-responsibility modules

Changes:
- Extract X from Y for Z responsibility
- Apply Factory pattern for object creation
- Apply Strategy pattern for interchangeable algorithms
- Reduce max file size from X to Y lines

Techniques used:
- Extract Class
- Extract Function
- Move Function
- Remove Dead Code

Refs: SOLID principles, refactoring.guru patterns"

git push -u origin refactor/cleanup-$(date +%Y-%m-%d)

6.2 Create PR

gh pr create --title "refactor: modularize codebase $(date +%Y-%m-%d)" --label "refactoring,automated" --body "$(cat <<'EOF'
## Summary

Automated refactoring to improve code organization and maintainability.

## Why These Changes?

### Problems Found
- [List specific code smells detected]
- [List files that were too large]
- [List responsibilities that were mixed]

### Solutions Applied
- [Explain each extraction and why]
- [Explain design patterns used and why]
- [Explain how SOLID principles are now respected]

## Changes Made

### Files Created
| New File | Responsibility | Lines | Extracted From |
|----------|---------------|-------|----------------|
| path/to/new.py | Description | XX | original.py |

### Files Modified
| File | Change |
|------|--------|
| path/to/file.py | Removed extracted code, updated imports |

## Metrics

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Largest file | X lines | Y lines | -Z% |
| Files > 100 lines | X | 0 | -100% |
| Avg file size | X | Y | -Z% |

## Design Patterns Applied

- **Pattern Name**: Why it was applied and benefit

## Refactoring Techniques Used

From [refactoring.com/catalog](https://refactoring.com/catalog/):
- Extract Class: [where and why]
- Extract Function: [where and why]
- Move Function: [where and why]

## SOLID Compliance

- [x] Single Responsibility: Each file has one reason to change
- [x] Open/Closed: New behavior via extension, not modification
- [x] Dependency Inversion: Depend on abstractions

## Testing

- [ ] All imports verified working
- [ ] Existing tests pass (if any)
- [ ] No circular dependencies
- [ ] Linter passes

## How to Review

1. Check each new file has a single, clear responsibility
2. Verify file sizes are reasonable (<60 lines ideally)
3. Confirm imports are clean and no circular dependencies
4. Run tests if available

## Rollback

If issues arise:
```bash
git revert <this-merge-commit>

EOF )"

---

## If No Refactoring Needed

If all files are already well-organized (under 60 lines, single responsibility):

```bash
gh issue create --title "✅ Code Quality Check - All Clean $(date +%Y-%m-%d)" --label "automated,quality" --body "$(cat <<'EOF'
## Daily Code Quality Check

**Status**: All code meets quality standards

### Metrics
- Largest file: X lines (under 60 limit)
- Files checked: Y
- Code smells found: 0

No refactoring needed today.
EOF
)"

Converted and distributed by TomeVault — claim your Tome and manage your conversions.