Refactor Legacy Code with AI

Analyze this legacy codebase and produce a structured health assessment. **About this codebase:** - Language/Framework: [e.g., Python 3.8 / Node.js 12 / PHP 7 / Java 8 + Spring] - Age: [e.g., '6 years old, grown from a side project'] - Size: [e.g., '~15,000 lines across 80 files'] - Current state: [Honest assessment — e.g., 'Works but nobody wants to touch it,' 'Frequent production bugs,' 'Adding features takes 3x longer than it should'] - Known problems: [What you already know is bad — e.g., 'God class with 2,000 lines,' 'No tests,' 'Everything reads from global state'] - Team knowledge: [Who understands this code — e.g., 'Original author left 2 years ago, limited documentation'] **Most important files/modules (paste the most problematic ones):** [File 1 — e.g., the main god class or entry point] ```[language] [Code] ``` [File 2 — paste another problematic file] ```[language] [Code] ``` For additional context, here is the full file listing: ``` [Output of `find . -name '*.py' | head -60` or equivalent] ``` Produce a structured assessment covering: 1. **Structural Problems** (rank by severity): God classes/modules, circular dependencies, hidden coupling, inappropriate responsibilities 2. **Code Quality Metrics** (estimate based on what you see): Average function length, max nesting depth, duplicated logic, unclear naming patterns 3. **Test Coverage**: Estimate based on any test files visible. What percentage of critical behavior is likely untested? 4. **Technical Debt Hotspots**: Which 3-5 specific files or functions are causing the most pain? Why? 5. **Risk Areas**: Where is a bug most likely to hide? Where would a change most likely break something unexpected? 6. **Dependencies**: Any outdated or deprecated dependencies visible? Any security-relevant packages? 7. **Effort Estimate**: Rough estimate of refactoring effort by category: Quick wins (< 1 day each), Medium tasks (1-3 days), Major overhauls (1+ week) 8. **What NOT to refactor**: Any code that's old and ugly but works and shouldn't be touched without strong justification? Be specific and blunt. Name the actual files and line numbers where problems are worst.

Based on the codebase assessment, help me create a prioritized, sequenced refactoring plan. **Assessment summary:** [Paste the key findings from Step 1 — the hotspots, structural problems, and effort estimates] **My constraints:** - Team size working on this: [e.g., '1 person / 2 engineers part-time'] - Time available: [e.g., '2-3 hours per week alongside feature work' or '2 dedicated weeks'] - Can I freeze feature development? [Yes for X weeks / No, must run in parallel] - Tolerance for risk: [e.g., 'This is internal tooling, some breakage is ok' or 'This is customer-facing, zero breakage tolerance'] - Must-not-touch areas: [e.g., 'The payment processing module — works fine and is compliance-audited'] **My goals for this refactoring:** [What specific outcome do you want? e.g., 'I want to be able to add a new feature type in 2 hours instead of 2 days' / 'I want to be able to onboard a new engineer without a week of knowledge transfer' / 'I want to stop having production incidents caused by this module'] Create a refactoring plan with: 1. **Phase 0: Safety Net** — What tests must I write BEFORE touching any code? (These prove current behavior so I can verify nothing breaks after changes.) 2. **Phase 1: Quick Wins** — Changes that improve things immediately with minimal risk. Criteria: can be done in < 4 hours each, easily reversible, don't change external interfaces. List 5-10 specific tasks. 3. **Phase 2: Structural Changes** — The bigger moves. For each one: - What specifically to do - What it enables (why this sequence position, not earlier or later) - Dependencies (must X be done before this?) - Estimated effort - Risk level and how to mitigate it 4. **Phase 3: Architecture Improvements** — Only if Phases 1-2 are complete and stable. What longer-term architectural goals should be on the roadmap? 5. **Stop Conditions**: When is 'good enough'? What's the point at which continuing to refactor provides diminishing returns and I should stop? 6. **Rollback Strategy**: For each phase, how do I roll back if something goes wrong in production? For each task, give me a one-line description I can put in a ticket. Be specific enough that someone else could do the task from the description.

Generate characterization tests for this code I'm about to refactor. These tests must capture existing behavior — including edge cases and even behaviors that might be bugs — so I can verify nothing changes during refactoring. **Code to test:** ```[language] [Paste the function, class, or module you're about to refactor] ``` **Testing framework available:** [pytest / Jest / JUnit / RSpec / Go test] **What this code is supposed to do** (based on my understanding): [Describe the intended behavior — e.g., 'Calculates a user's invoice total, applying discounts and taxes'] **Known inputs and outputs** (any examples I already know): [List any examples you know — e.g., 'empty cart should return 0' / 'our QA engineer confirmed that passing X returns Y'] **External dependencies this code has:** [List what it calls — e.g., 'Reads from database via db.query(),' 'Calls external payment API,' 'Reads from global config object'] Generate: 1. **Characterization tests that call this code with varied inputs and record the outputs.** For each test: - A descriptive name of what scenario it covers - The input - The expected output (derive from the code's actual logic — NOT from what you think is correct) - A comment flagging if this output looks like it might be a bug I should be aware of 2. **Coverage of these input categories:** - Normal/happy path inputs (3-5 tests) - Boundary values (empty, null, zero, max) - Edge cases visible in the code (anything that triggers a specific branch or condition) - Error cases (what happens when dependencies fail) 3. **Mocks/stubs for external dependencies** so tests run in isolation and don't hit the real database or external services 4. **A test that captures the full integration behavior** if the function is part of a larger flow (not just unit testing individual branches) After generating the tests, run them and make sure they all pass BEFORE I start refactoring. If any fail, tell me — that indicates a bug I need to understand before proceeding. **Important**: I want tests that describe what the code DOES, not what it SHOULD do. We'll add 'correct behavior' tests after the refactoring is complete.

Refactor this code. I have characterization tests in place that will tell me if behavior changes. **Code to refactor:** ```[language] [Paste the specific function or class to refactor] ``` **Refactoring goal for this task:** [Be specific — e.g., 'Extract the tax calculation logic into a separate TaxCalculator class' / 'Replace the 300-line process_order function with smaller single-responsibility functions' / 'Remove global state by passing configuration as a parameter'] **Constraints:** - **Do not change external interfaces**: The function signatures, return types, and any behavior that callers depend on must stay identical. I'll update callers separately if needed. - **Do not fix bugs** (unless explicitly listed): Even if you see logic errors, don't fix them — changing behavior (even to fix bugs) will break my characterization tests and make it hard to tell if refactoring caused a problem. - **Known bugs I'm intentionally preserving for now:** [List any bugs you're aware of that characterization tests encode] - **Style guide:** [e.g., 'Follow PEP 8 / Airbnb JS style / Google Java style'] **Specific refactoring patterns to apply:** [Choose from these or specify your own] - [ ] Extract Method: Pull [specific logic] into its own function named [suggested name] - [ ] Extract Class: Move [specific responsibilities] into a new class named [suggested name] - [ ] Replace Magic Numbers: [list the magic numbers] should become named constants - [ ] Replace Conditional with Polymorphism - [ ] Introduce Parameter Object: [list parameters] should be a [ClassName] object - [ ] Remove Dead Code: [identify dead code to remove] - [ ] Rename for Clarity: [old names] → [better names] **Provide:** 1. The refactored code 2. A list of every change made (one line per change) 3. Any new files or classes created and where they should live 4. Any callers of the original code that now need updating 5. Notes on anything you explicitly chose NOT to change and why After I apply this, I'll run the characterization tests. If any fail, I'll paste the failure and we'll debug together.

The refactoring is complete and all characterization tests pass. Now help me improve the test suite. **Refactored code:** ```[language] [Paste the final refactored code] ``` **Current characterization tests:** ```[language] [Paste the characterization tests from Step 3] ``` **Bugs I found during refactoring that I now want to fix:** 1. [Bug 1 — e.g., 'Tax is incorrectly applied to items marked as tax-exempt'] 2. [Bug 2 — e.g., 'Function returns None instead of empty list when no results found'] **Part 1: Upgrade Characterization Tests to Specification Tests** Review my characterization tests. For each test: - If it captures correct behavior: convert it to a proper specification test with a name that describes the INTENDED behavior (not just 'this is what the code does') - If it captures a bug I'm now fixing: update the expected output to the correct behavior - If it's redundant with another test: mark it for deletion - If there's a test gap — important behavior that isn't covered: add it Return an updated, clean test file. **Part 2: Add Tests for the Bugs I Fixed** For each bug listed above, write a regression test that: - Would have caught this bug BEFORE the fix (and fails against the old code) - Passes against the fixed code - Has a name that makes the bug scenario clear (so if this test ever fails again, the name tells you exactly what broke) **Part 3: Documentation** For the refactored module, generate: 1. A module-level docstring that explains: what this module does, key design decisions, anything non-obvious about the implementation 2. Docstrings for any public functions/methods that were unclear before 3. Inline comments for any logic that is still complex after refactoring **Part 4: Health Check** Looking at the final refactored code and test suite: what risks remain? What should be the next refactoring task if I were to continue? Is there anything I should monitor in production after deploying this change?