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

git add .
git commit -m "Refactoring: complete"