gps-denied-onboard/_docs/tutorial_refactor.md

# Refactoring Existing Project

This tutorial guides through analyzing, documenting, and refactoring an existing codebase.

## Reference Documents
 - Definition of Done: `@_docs/00_templates/definition_of_done.md`
 - Quality Gates: `@_docs/00_templates/quality_gates.md`
 - Feature Parity Checklist: `@_docs/00_templates/feature_parity_checklist.md`
 - Baseline Metrics: `@_docs/04_refactoring/baseline_metrics.md` (created in 4.07)


## 4.05 **🧑‍💻 Developers**: User Input

 ### Define Goals
  Create in `_docs/00_problem`:
  - `problem_description.md`: What system currently does + what you want to change/improve
  - `acceptance_criteria.md`: Success criteria for the refactoring
  - `security_approach.md`: Security requirements (if applicable)


## 4.07 **🤖📋AI plan**: Capture Baseline Metrics

  ### Execute `/4.refactoring/4.07_capture_baseline`

  ### Revise
   - Verify all metrics are captured accurately
   - Document measurement methodology
   - Save raw data for later comparison

  ### Store
   - Create folder `_docs/04_refactoring/`
   - Save output to `_docs/04_refactoring/baseline_metrics.md`

  ### Create Feature Parity Checklist
   - Copy `@_docs/00_templates/feature_parity_checklist.md` to `_docs/04_refactoring/`
   - Fill in current feature inventory


## 4.10 **🤖📋AI plan**: Build Documentation from Code

  ### Execute `/4.refactoring/4.10_documentation`

  ### Revise
   - Review generated component docs
   - Verify accuracy against actual code behavior


## 4.20 **🤖📋AI plan**: Form Solution with Flows

  ### Execute `/4.refactoring/4.20_form_solution_flows`

  ### Revise
   - Review solution description
   - Verify flow diagrams match actual system behavior
   - Store to `_docs/01_solution/solution.md`


## 4.30 **🤖✨AI Research**: Deep Research of Approaches

  ### Execute `/4.refactoring/4.30_deep_research`

  ### Revise
   - Review suggested improvements
   - Prioritize changes based on impact vs effort


## 4.35 **🤖✨AI Research**: Solution Assessment with Codebase

  ### Execute `/4.refactoring/4.35_solution_assessment`

  ### Revise
   - Review weak points identified in current implementation
   - Decide which to address


## 4.40 **🤖📋AI plan**: Integration Tests Description

  ### Execute `/4.refactoring/4.40_tests_description`

  ### Prerequisites Check
   - Baseline metrics captured (4.07)
   - Feature parity checklist created

  ### Coverage Requirements
   - Minimum overall coverage: 75%
   - Critical path coverage: 90%
   - All public APIs must have integration tests

  ### Revise
   - Ensure tests cover critical functionality
   - Add edge cases


## 4.50 **🤖📋AI plan**: Implement Tests

  ### Execute `/4.refactoring/4.50_implement_tests`

  ### Verify
   - All tests pass on current codebase
   - Tests serve as safety net for refactoring
   - Coverage meets requirements (75% minimum)

  ### Quality Gate: Safety Net Ready
  Review `@_docs/00_templates/quality_gates.md` - Refactoring Gate 1


## 4.60 **🤖📋AI plan**: Analyze Coupling

  ### Execute `/4.refactoring/4.60_analyze_coupling`

  ### Revise
   - Review coupling analysis
   - Prioritize decoupling strategy


## 4.70 **🤖📋AI plan**: Execute Decoupling

  ### Execute `/4.refactoring/4.70_execute_decoupling`

  ### Verify After Each Change
   - Run integration tests after each change
   - All tests must pass before proceeding
   - Update feature parity checklist

  ### Quality Gate: Refactoring Safe
  Review `@_docs/00_templates/quality_gates.md` - Refactoring Gate 2


## 4.80 **🤖📋AI plan**: Technical Debt

  ### Execute `/4.refactoring/4.80_technical_debt`

  ### Revise
   - Review debt items
   - Prioritize by impact


## 4.90 **🤖📋AI plan**: Performance Optimization

  ### Execute `/4.refactoring/4.90_performance`

  ### Verify
   - Compare against baseline metrics from 4.07
   - Performance should be improved or maintained
   - Run tests to ensure no regressions


## 4.95 **🤖📋AI plan**: Security Review

  ### Execute `/4.refactoring/4.95_security`

  ### Verify
   - Address identified vulnerabilities
   - Run security tests if applicable


## 4.97 **🧑‍💻 Developer**: Final Verification

  ### Quality Gate: Refactoring Complete
  Review `@_docs/00_templates/quality_gates.md` - Refactoring Gate 3

  ### Compare Against Baseline
   - [ ] Code coverage >= baseline
   - [ ] Performance metrics improved or maintained
   - [ ] All features preserved (feature parity checklist complete)
   - [ ] Technical debt reduced

  ### Feature Parity Verification
   - [ ] All items in feature parity checklist verified
   - [ ] No functionality lost
   - [ ] All tests pass

  ### Documentation
   - [ ] Update solution.md with changes
   - [ ] Document any intentional behavior changes
   - [ ] Update README if needed

  ### Commit
   ```bash
   git add .
   git commit -m "Refactoring: complete"
   ```