tdd-refactor

name	tdd-refactor
description	Improve code quality, apply best practices, and enhance design whilst maintaining green tests. Use after tests pass and the code needs cleanup, when the user asks to refactor, or when code smells need to be addressed without changing behaviour.

TDD Refactor Phase - Improve Code Quality and Design

Quality Gates

• Definition of Done adherence - Ensure all tests are passing by running all tests before starting any activity.
• Code smells - Identify and eliminate code smells such as duplicated code, long methods, large classes, and complex conditionals.
• Security requirements - Address any security considerations.
• Performance criteria - Meet any performance requirements.

Core Principles

Code Quality Improvements

• Remove duplication - Extract common code into reusable classes and methods. Follow the "Rule of Three" meaning knowledge should be abstracted only after it has been used in three places.
• Improve readability - Use intention-revealing names and clear structure aligned with the domain.
• Apply SOLID principles
  • Single Responsibility Principle - Ensure each class and method has one and only one reason to change.
  • Open/Closed Principle - Make code open for extension but closed for modification.
  • Liskov Substitution Principle - Subtypes must be substitutable for their base types.
  • Interface Segregation Principle - Use specific abstract classes rather than general ones.
  • Dependency Inversion Principle - Depend on abstractions, not concrete implementations.
• Simplify complexity - Break down large methods, reduce cognitive and cyclomatic complexities.

Design Excellence

• Class length - Keep the length of classes under 100 lines.
• Method length - Keep the length of methods under 10 lines.
• Composition over inheritance - Prefer writing small focused classes and compose behaviour from them.
• Dependency injection - Use dependency injection through class constructor arguments.
• Modularization - Organize code into coherent modules and packages.
• Pydantic models - Leverage Pydantic for configuration objects, data, and domain models.

Test Quality

• Fast tests - Ensure tests remain fast and isolated.
• Coverage maintenance - Test coverage must not decrease during refactoring.

Safe Refactoring Patterns

Use battle-tested refactoring techniques:

• Extract Constant - Move magic numbers and strings to named constants.
• Extract Method - Break down long methods into smaller ones.
• Extract Class - Split large classes with multiple responsibilities.
• Rename - Use intention-revealing names for variables, methods, and classes.
• Inline Variable/Method - Simplify code by removing unnecessary indirection.
• Move Method/Field - Relocate code to more appropriate locations.
• Replace Conditional with Polymorphism - Use objects instead of complex conditionals.

Documentation

• Update documentation - Revise inline comments and docstrings to match refactored code. Ensure the documentation always answers to question WHY instead of WHAT.
• Record decisions - Document non-obvious design decisions made during refactoring.

Performance & Quality Validation

• Avoid premature optimization - Only optimize when there are actual performance issues.
• Remove dead code - Eliminate unused imports, variables, and unreachable code.
• Run static analysis - Use linters and type checkers to catch issues early.

Execution Guidelines

1. Ensure green tests - All tests must pass before refactoring can start. Verify this by running all tests.
2. Small incremental changes - Refactor in tiny, atomic steps.
3. Apply one improvement at a time - Focus on a single refactoring technique.
4. No test code modifications - Do NOT modify any test code during refactoring.
5. Continuous testing - Run tests after EACH and EVERY change.
6. Coverage preservation - Ensure test coverage doesn't decrease during refactoring.
7. Static analysis - Run linters and static analysis tools after changes.
8. API stability - Validate that publicly exposed APIs and contracts remain unchanged.
9. Rollback readiness - Revert to a previous working state when tests become unstable or complexity increases to the point you cannot reason about the changes.

Refactor Phase Checklist

Before Starting

• All tests pass before starting.
• Current test coverage recorded.

During Refactoring

• Linters and static analysis tools run successfully.
• Tests pass after every change.
• Specific refactoring technique documented.
• No modifications made to test code.

After Refactoring

• Code readability and design improved.
• All tests remain green.
• Test coverage is maintained or improved.
• Public APIs and contracts unchanged.
• Unused code removed (imports, variables, dead code).
• Documentation updated (comments, docstrings).
• Performance improved where applicable.

Technical Debt

• Remaining refactoring opportunities documented and suggested to the user.
• Non-obvious design decisions recorded.
• Breaking changes or impacts flagged.