Refactor Messy AI Code

The route

6 steps to Done

1. 01

   Capture the behavior baseline

   You cannot verify 'nothing broke' without a before-list.

   Preview prompt + verify gate ▾ Hide ▴

   Before any refactoring, produce the behavior baseline: a checklist of every feature and its verifiable behavior (action -> expected result), covering all pages, forms, and CRUD operations. Execute the checklist now and record PASS/FAIL per item - this snapshot is the contract every later stage must re-verify against. Also list known-broken items so they are not blamed on the refactor.

   • ✓ Every feature has a verifiable behavior entry
   • ✓ The checklist was executed, not assumed
   • ✓ Pre-existing breakage is recorded separately
2. 02

   Map the mess

   Diagnose duplication, dead code, and oversized files before cutting.

   Preview prompt + verify gate ▾ Hide ▴

   Analyze the codebase and report: duplicated logic (same/near-same code in multiple places, with locations); dead code (unused components, functions, imports, routes); files over ~300 lines mixing concerns; inconsistent patterns (different API call styles, state approaches, naming). Output a refactor plan of small, ordered, independently-verifiable passes.

   • ✓ Duplications listed with file locations
   • ✓ Dead code candidates verified as unused
   • ✓ The plan is split into small verifiable passes
3. 03

   Remove dead code

   Delete what is provably unused - the safest first win.

   Preview prompt + verify gate ▾ Hide ▴

   Execute the dead-code pass. Requirements: remove unused components, functions, imports, styles, and routes identified in the map - but verify each is truly unreferenced before deleting (search for dynamic usage too); the app must build cleanly after; re-run the behavior baseline and confirm all previous PASSes still pass. Report what was deleted and the re-verification result.

   • ✓ Each deletion was reference-checked first
   • ✓ The build is clean
   • ✓ Baseline re-run passes
4. 04

   Deduplicate shared logic

   One source of truth for each behavior.

   Preview prompt + verify gate ▾ Hide ▴

   Execute the dedupe pass. Requirements: extract duplicated logic into shared utilities/hooks/components; where near-duplicates differ, preserve BOTH behaviors explicitly (parameterize, do not silently pick one); update all call sites; re-run the baseline after each extraction batch. Report each extraction with its call sites and verification result.

   • ✓ Near-duplicate differences were preserved deliberately
   • ✓ All call sites updated
   • ✓ Baseline passes after each batch
5. 05

   Split oversized files and unify patterns

   Restructure for maintainability with mechanical, verifiable moves.

   Preview prompt + verify gate ▾ Hide ▴

   Execute the structure pass. Requirements: split files over ~300 lines into focused modules/components (pure moves - no logic edits in the same change); standardize API calls into a single client/pattern and state handling into one consistent approach; fix imports everywhere; build cleanly and re-run the full baseline at the end. Report the new structure map.

   • ✓ Splits were pure moves without logic edits
   • ✓ One API-call pattern remains
   • ✓ Full baseline passes at the end
6. 06

   Final verification and guardrails

   Prove the refactor kept its promise and leave the code defensible.

   Preview prompt + verify gate ▾ Hide ▴

   Run the complete behavior baseline one final time and report PASS/FAIL per item versus the original snapshot - any regression gets fixed now. Then add lightweight guardrails: remove remaining console noise, add error boundaries if missing, and write a brief architecture note (folder structure, where things live, the standard patterns) so future changes stay consistent.

   • ✓ Final baseline matches or beats the original
   • ✓ All regressions fixed
   • ✓ Architecture note written