refactoring-plan

name	refactoring-plan
description	Multi-phase refactoring and optimization plan with strict validation gates. Covers knowledge acquisition, API rationalization, project structure cleanup, code quality implementation (ruff, mypy, black), security and cost optimization, documentation, and emergency rollback protocols.
user-invokable	true
args	[{"name":"target","description":"The project to create a refactoring plan for (optional)","required":false}]

Systematically refactor, clean up, and optimize the codebase. Work methodically through sequential phases with strict validation gates. DO NOT proceed to the next phase until the current phase is 100% complete with evidence.

Phase 0: Knowledge Acquisition (MANDATORY FIRST)

Complete this before making ANY code changes.

1. Research RESTful API design patterns, Python project structure standards, code quality tooling configurations, auth/security patterns, and document processing architectures.
2. Analyze the codebase: complete symbol mapping, duplicate code identification, API endpoint analysis, orphaned code detection, naming inconsistency audit.

Gate 0 Evidence Required:

• Complete research summary with citations
• Full codebase symbol map
• Duplicate code identification matrix
• API endpoint analysis report
• Security vulnerability assessment

Phase 1: API Endpoint Rationalization

1. Design unified endpoint structure with parameter-based functionality.
2. Standardize parameters: ocr_mode, processing_mode, output_format, validation_level.
3. Plan backward compatibility for existing clients.

Gate 1 Evidence Required:

• OpenAPI 3.0 specification
• Working implementation with all parameter combinations
• 100% test coverage for new API structure
• Backward compatibility tests passing
• Performance benchmarks

Phase 2: Project Structure Cleanup

1. Implement clean architecture: api/, core/, models/, services/, utils/, config/, tests/.
2. Eliminate ALL code duplication.
3. Fix naming conventions across entire codebase.

Gate 2 Evidence Required:

• Zero duplicate code detected by static analysis
• All modules follow single responsibility
• No circular imports
• Consistent naming conventions
• Complete migration of all functionality

Phase 3: Code Quality Implementation

1. Implement tooling:

[tool.ruff]
select = ["E", "F", "W", "I", "N", "B", "A", "C90", "UP"]
line-length = 88

[tool.mypy]
python_version = "3.9"
strict = true

[tool.black]
line-length = 88
target-version = ['py39']

Gate 3 Evidence Required:

• All linting passes without errors
• MyPy 100% compliant
• Test coverage ≥85%
• Security scan: zero critical/high issues
• Performance benchmarks within acceptable ranges

Phase 4: Security & Cost Optimization

1. Input validation for all endpoints, secure token handling, rate limiting, secure file upload.
2. Intelligent model selection, request caching/batching, cost monitoring, error handling to prevent API waste.

Gate 4 Evidence Required:

• OWASP compliance verification
• Penetration testing results
• Cost optimization metrics
• Complete audit trail
• Performance under load

Phase 5: Documentation & Validation

1. Complete API documentation, developer setup guide, architecture decision records, troubleshooting guides.
2. End-to-end testing, performance validation, security re-verification.

Gate 5 Evidence Required:

• 100% API documentation coverage
• New developer onboarding <1 day
• All test data processes correctly
• Performance meets or exceeds original
• Security compliance maintained

Emergency Protocols

Rollback Strategies

• Phase-level git tags for reversion.
• Critical file backups before modification.
• API versioning for zero-downtime rollback.
• Backward-compatible database migrations.

Quality Gates That Cannot Be Bypassed

1. All existing functionality continues working.
2. No performance degradation >10%.
3. Zero high/critical security vulnerabilities.
4. Minimum 85% code coverage maintained.
5. All public interfaces documented.

Validation Protocol

After Each Phase:

1. Run comprehensive test suite.
2. Perform static analysis validation.
3. Generate evidence report.
4. Get explicit confirmation before proceeding.

If Any Gate Fails:

1. STOP immediately.
2. Analyze root cause.
3. Fix issues completely.
4. Re-validate before proceeding.

Success Criteria

• API endpoints use logical naming with parameter-based functionality
• Zero duplicate code across entire codebase
• All quality tools pass without errors
• Security audit: zero critical/high vulnerabilities
• Performance meets or exceeds current system
• Documentation enables immediate developer productivity
• Cost optimization shows measurable improvement
• Project structure follows best practices with clear separation of concerns